zhyang-dev/LPP
1
0
Fork 0
mirror of https://github.com/ParticulateFlow/LPP.git synced 2025-12-08 06:37:46 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Committer: ckloss <ckloss@fluid38.(none)>

Browse Source 
On branch master
 Initial commit for lpp, version 2011-10-11
This commit is contained in:
ckloss
2012-02-03 14:10:31 +01:00
commit 80592c0da1
227 changed files with 119295 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
INSTALL.txt Normal file
View File

@ -0,0 +1,8 @@
to install liggghts post processing copy the following lines of code into your bashrc (please change the variable CFDEM_lppPath according to your system):
============================================
CFDEM_lppPath=/Users/s/work/parallelpizza/nightly_build
alias lpp="python $CFDEM_lppPath/src/lpp.py"
alias pizza ="python $CFDEM_lppPath/src/pizza.py"
============================================

350
LICENSE Normal file
View File

@ -0,0 +1,350 @@
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your freedom
to share and change it. By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on,
we want its recipients to know that what they have is not the
original, so that any problems introduced by others will not reflect
on the original authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at
all.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains a
notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the Program
(independent of having been made by running the Program). Whether that
is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously
and appropriately publish on each copy an appropriate copyright notice
and disclaimer of warranty; keep intact all the notices that refer to
this License and to the absence of any warranty; and give any other
recipients of the Program a copy of this License along with the
Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Program or any portion of
it, thus forming a work based on the Program, and copy and distribute
such modifications or work under the terms of Section 1 above,
provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that
in whole or in part contains or is derived from the Program or
any part thereof, to be licensed as a whole at no charge to all
third parties under the terms of this License.
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you
provide a warranty) and that users may redistribute the program
under these conditions, and telling the user how to view a copy
of this License. (Exception: if the Program itself is interactive
but does not normally print such an announcement, your work based
on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Sections 1 and 2 above on a medium customarily used for software
interchange; or,
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt otherwise
to copy, modify, sublicense or distribute the Program is void, and
will automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted
herein. You are not responsible for enforcing compliance by third
parties to this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new
versions of the General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Program does not specify a
version number of this License, you may choose any version ever
published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the
author to ask for permission. For software which is copyrighted by the
Free Software Foundation, write to the Free Software Foundation; we
sometimes make exceptions for this. Our decision will be guided by the
two goals of preserving the free status of all derivatives of our free
software and of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest to
attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does.
Copyright (C) yyyy name of author
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'. This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License. Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.
You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.
signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library,
you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use the
GNU Library General Public License instead of this License.

41
README Normal file
View File

@ -0,0 +1,41 @@
This is the Pizza.py (1 Oct 2006) software package.
Copyright (2005) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
----------------------------------------------------------------------
Pizza.py is a loosely integrated collection of tools written in
Python, many of which provide pre- and post-processing capability for
the LAMMPS molecular dynamics package. There are tools to create
input files, convert between file formats, process log and dump files,
create plots, and visualize and animate simulation snapshots.
Pizza.py was developed at Sandia National Laboratories, a US
Department of Energy facility, with funding from the DOE. It is an
open-source code, distributed freely under the terms of the GNU Public
License (GPL).
The maintainer of Pizza.py is Steve Plimpton, who can be emailed at
sjplimp@sandia.gov. The Pizza.py WWW site
(www.cs.sandia.gov/~sjplimp/lammps.html) and LAMMPS WWW Site
(www.cs.sandia.gov/~sjplimp/lammps.html) have more information about
the code and its uses.
The Pizza.py (1 Oct 2006) distribution includes the following files
and directories:
README this file
LICENSE the GNU open-source license
doc HTML documentation for Pizza.py
examples scripts and data sets that exercise Pizza.py tools
scripts various Pizza.py script files
src source code for Pizza.py and its tools
Point your browser at any of these files to get started:
doc/Manual.html the Pizza.py manual
doc/Section_intro.html hi-level introduction to Pizza.py
doc/Section_install.html how to install Pizza.py

28
README_GRANULAR Normal file
View File

@ -0,0 +1,28 @@
=================================================================
This is lpp (liggghts post processing), an update to pizza.py offering better visualization
of granular (DEM) LIGGGHTS or LAMMPS simulations using pizza.py
LAMMPS=Large Atomic and Molecular Massively Parallel Simulator.
http://lammps.sandia.gov/
LIGGGHTS=LAMMPS Improved for General Granular and Granular
Heat Transfer Simulations
http://www.liggghts.com // www.cfdem.com
pizza.py=LAMMPS post processor
http://www.sandia.gov/~sjplimp/pizza.html
=================================================================
Christoph Kloss, Linz, Aug. 2010 -
Stefan Amberger Linz, July 2011 -
Philippe Seil Linz, Sept 2011 -
all
Christian-Doppler Laboratory on Particulate Flow Modelling
Institute of Fluid Mechanics and Heat Transfer
Johannes Kepler University,
Altenbergerstrasse 69, A-4040 Linz/Austria
www.particulate-flow.at
=================================================================
For information on how to use the lpp tool, see doc/lpp.html

18
changelog_lpp.txt Normal file
View File

@ -0,0 +1,18 @@
2011-10-11 - Christoph Kloss
+ included pizza patches from Steve Plimpton (Sandia) until 2011-10-07 OK
+ changed the doc in pizza-style (removed readme_granular.txt, new lpp.txt/html file) OK
+ Automatic recognition of variables extended to computes (c_) and variables (v_) OK
+ included a new functionality written by Mark Bentley (Space Research Institute, Austrian Academy of Sciences)
to convert dump/local output into VTK to viz stress chains TODO
+ test+debug force chains TODO
2011-09-27 - Philippe Seil
+ added LPP command line options that give control over things like output filenames, chunksizes etc.
2011-08-10 - Stefan Amberger
+ bugfix for (dump.py, vtk.py) parallelpizza would crash if empty dumpfiles were processed (i.e. number of atoms == 0)
2011-08-12 - Stefan Amberger
+ removed (vtk.py) the binding of variables to specific positions in liggghts dump files.
scalars / vectors are now recognized automatically (rules: x,y,z in the end --> vector; f_variable[i], f_variable[i+1], f_variable[i+2] --> vector)
+ lpp now uses command line arguments. new usage: User$ lpp dump*

205
doc/Manual.html Normal file
View File

@ -0,0 +1,205 @@
<HTML>
<HEAD>
<TITLE>Pizza.py Users Manual</TITLE>
<META NAME="docnumber" CONTENT="Pizza.py Toolkit">
<META NAME="author" CONTENT="http://www.sandia.gov/~sjplimp/pizza.html - Sandia National Laboratories">
<META NAME="copyright" CONTENT="Copyright (2005) Sandia Corporation. This software and manual is distributed under the GNU General Public License.">
</HEAD>
<BODY>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H1></H1>
<CENTER><H3>Pizza.py Documentation
</H3></CENTER>
<H4>Version info:
</H4>
<P>The Pizza.py "version" is the date when it was released, such as 1 May
2010. Pizza.py is updated continuously. Whenever we fix a bug or add a
feature, we release it immediately, and post a notice on <A HREF = "http://www.cs.sandia.gov/pizza/bug.html">this page of
the WWW site</A>. Each dated copy of Pizza.py contains all the
features and bug-fixes up to and including that version date. The
version date is printed to the screen and logfile every time you run
Pizza.py. It is also in the file src/version.h and in the Pizza.py
directory name created when you unpack a tarball.
</P>
<UL><LI>If you browse the HTML or PDF doc pages on the Pizza.py WWW site, they
always describe the most current version of Pizza.py.
<LI>If you browse the HTML or PDF doc pages included in your tarball, they
describe the version you have.
</UL>
<P>Pizza.py is a loosely integrated collection of tools written in
Python, many of which provide pre- and post-processing capability for
the <A HREF = "http://www.cs.sandia.gov/~sjplimp/lammps.html">LAMMPS</A> molecular dynamics and <A HREF = "cccell">ChemCell</A> cell
simulator packages. There are tools to create input files, convert
between file formats, process log and dump files, create plots, and
visualize and animate simulation snapshots.
</P>
<P>The name Pizza.py is meant to evoke the aroma of a collection of
"toppings" that the user can combine in different ways on a "crust" of
basic functionality, with Python as the "cheese" that glues everything
together.
</P>
<P>The maintainer of Pizza.py is <A HREF = "http://www.cs.sandia.gov/~sjplimp">Steve
Plimpton</A> at <A HREF = "http://www.sandia.gov">Sandia National
Laboratories</A>, a US Department of Energy (<A HREF = "http://www.doe.gov">DOE</A>)
laboratory. Many of the tools were written by Matt Jones, a BYU
student who spent a summer at Sandia. The <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> at
www.cs.sandia.gov/~sjplimp/pizza.html has more information about
Pizza.py and its uses.
</P>
<HR>
<P>The Pizza.py documentation is organized into the following sections.
If you find errors or omissions in this manual or have suggestions for
useful information to add, please send an email to sjplimp@sandia.gov
so we can improve the Pizza.py documentation.
</P>
<P><A HREF = "Manual.pdf">PDF file</A> of the entire manual, generated by
<A HREF = "http://www.easysw.com/htmldoc">htmldoc</A>
</P>
<OL><LI><A HREF = "Section_intro.html">Introduction</A>
<UL> 1.1 <A HREF = "Section_intro.html#1_1">What is Pizza.py</A>
<BR>
1.2 <A HREF = "Section_intro.html#1_2">Open source distribution</A>
<BR>
1.3 <A HREF = "Section_intro.html#1_3">Acknowledgements</A>
<BR></UL>
<LI><A HREF = "Section_install.html">Installing Pizza.py</A>
<UL> 2.1 <A HREF = "Section_install.html#2_1">Installing Python</A>
<BR>
2.2 <A HREF = "Section_install.html#2_2">Running Pizza.py</A>
<BR>
2.3 <A HREF = "Section_install.html#2_3">Setting up the DEFAULTS.py file</A>
<BR>
2.4 <A HREF = "Section_install.html#2_4">Installing additional Python packages</A>
<BR>
2.5 <A HREF = "Section_install.html#2_5">Installing other software</A>
<BR></UL>
<LI><A HREF = "Section_basics.html">Basics of using Pizza.py</A>
<UL> 3.1 <A HREF = "Section_basics.html#3_1">Python syntax</A>
<BR>
3.2 <A HREF = "Section_basics.html#3_2">Pizza.py command line arguments</A>
<BR>
3.3 <A HREF = "Section_basics.html#3_3">Pizza.py extensions to the Python interpreter</A>
<BR>
3.4 <A HREF = "Section_basics.html#3_4">Using Pizza.py tools</A>
<BR>
3.5 <A HREF = "Section_basics.html#3_5">Runnning Pizza.py and Python scripts</A>
<BR>
3.6 <A HREF = "Section_basics.html#3_6">Error messages</A>
<BR></UL>
<LI><A HREF = "Section_tools.html">Tools within Pizza.py</A>
<LI><A HREF = "Section_examples.html">Example scripts</A>
<LI><A HREF = "Section_extend.html">Extending Pizza.py</A>
</OL>
<HR>
<P>List of tools in Pizza.py:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD ><A HREF = "animate.html">animate.py</A></TD><TD > Animate a series of image files</TD></TR>
<TR><TD ><A HREF = "bdump.html">bdump.py</A></TD><TD > Read LAMMPS dump local files with bond info</TD></TR>
<TR><TD ><A HREF = "cdata.html">cdata.py</A></TD><TD > Read, write, manipulate <A HREF = "http://www.cs.sandia.gov/~sjplimp/chemcell.html">ChemCell</A> data files</TD></TR>
<TR><TD ><A HREF = "chain.html">chain.py</A></TD><TD > Create bead-spring chains for LAMMPS input</TD></TR>
<TR><TD ><A HREF = "cfg.html">cfg.py</A></TD><TD > Convert LAMMPS snapshots to CFG format</TD></TR>
<TR><TD ><A HREF = "clog.html">clog.py</A></TD><TD > Read <A HREF = "http://www.cs.sandia.gov/~sjplimp/chemcell.html">ChemCell</A> log files and extract species data</TD></TR>
<TR><TD ><A HREF = "data.html">data.py</A></TD><TD > Read, write, manipulate LAMMPS data files</TD></TR>
<TR><TD ><A HREF = "dump.html">dump.py</A></TD><TD > Read, write, manipulate dump files and particle attributes</TD></TR>
<TR><TD ><A HREF = "ensight.html">ensight.py</A></TD><TD > Convert LAMMPS snapshots to <A HREF = "http://www.ensight.com">Ensight</A> format</TD></TR>
<TR><TD ><A HREF = "gl.html">gl.py</A></TD><TD > 3d interactive visualization via OpenGL</TD></TR>
<TR><TD ><A HREF = "gnu.html">gnu.py</A></TD><TD > Create plots via <A HREF = "http://www.gnuplot.info">GnuPlot</A> plotting program</TD></TR>
<TR><TD ><A HREF = "histo.html">histo.py</A></TD><TD > Particle density histogram from a dump</TD></TR>
<TR><TD ><A HREF = "image.html">image.py</A></TD><TD > View and manipulate images</TD></TR>
<TR><TD ><A HREF = "ldump.html">ldump.py</A></TD><TD > Read LAMMPS dump files with line info</TD></TR>
<TR><TD ><A HREF = "log.html">log.py</A></TD><TD > Read LAMMPS log files and extract thermodynamic data</TD></TR>
<TR><TD ><A HREF = "matlab.html">matlab.py</A></TD><TD > Create plots via <A HREF = "http://www.mathworks.com">MatLab</A> numerical analysis program</TD></TR>
<TR><TD ><A HREF = "mdump.html">mdump.py</A></TD><TD > Read, write, manipulate mesh dump files</TD></TR>
<TR><TD ><A HREF = "pair.html">pair.py</A></TD><TD > Compute LAMMPS pairwise energies</TD></TR>
<TR><TD ><A HREF = "patch.html">patch.py</A></TD><TD > Create patchy Lennard-Jones particles for LAMMPS input</TD></TR>
<TR><TD ><A HREF = "pdbfile.html">pdbfile.py</A></TD><TD > Read, write PDB files in combo with LAMMPS snapshots</TD></TR>
<TR><TD ><A HREF = "plotview.html">plotview.py</A></TD><TD > Plot multiple vectors from a data set</TD></TR>
<TR><TD ><A HREF = "rasmol.html">rasmol.py</A></TD><TD > 3d visualization via <A HREF = "http://www.openrasmol.org">RasMol</A> program</TD></TR>
<TR><TD ><A HREF = "raster.html">raster.py</A></TD><TD > 3d visualization via <A HREF = "http://www.bmsc.washington.edu/raster3d/raster3d.html">Raster3d</A> program</TD></TR>
<TR><TD ><A HREF = "svg.html">svg.py</A></TD><TD > 3d visualization via <A HREF = "http://www.w3.org/Graphics/SVG">SVG</A> files</TD></TR>
<TR><TD ><A HREF = "tdump.html">tdump.py</A></TD><TD > Read LAMMPS dump files with triangle info</TD></TR>
<TR><TD ><A HREF = "vcr.html">vcr.py</A></TD><TD > VCR-style GUI for 3d interactive OpenGL visualization</TD></TR>
<TR><TD ><A HREF = "vec.html">vec.py</A></TD><TD > Create numeric vectors from columns in file or list of vecs</TD></TR>
<TR><TD ><A HREF = "vtk.html">vtk.py</A></TD><TD > Convert LAMMPS snapshots to VTK format</TD></TR>
<TR><TD ><A HREF = "vmd.html">vmd.py</A></TD><TD > Wrapper on <A HREF = "http://www.ks.uiuc.edu/Research/vmd">VMD visualization package</A></TD></TR>
<TR><TD ><A HREF = "xyz.html">xyz.py</A></TD><TD > Convert LAMMPS snapshots to XYZ format
</TD></TR></TABLE></DIV>
</HTML>

BIN
doc/Manual.pdf Normal file
View File

Binary file not shown.

156
doc/Manual.txt Normal file
View File

@ -0,0 +1,156 @@
<HEAD>
<TITLE>Pizza.py Users Manual</TITLE>
<META NAME="docnumber" CONTENT="Pizza.py Toolkit">
<META NAME="author" CONTENT="http://www.sandia.gov/~sjplimp/pizza.html - Sandia National Laboratories">
<META NAME="copyright" CONTENT="Copyright (2005) Sandia Corporation. This software and manual is distributed under the GNU General Public License.">
</HEAD>
<BODY>
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
<H1></H1>
Pizza.py Documentation :c,h3
Version info: :h4
The Pizza.py "version" is the date when it was released, such as 1 May
2010. Pizza.py is updated continuously. Whenever we fix a bug or add a
feature, we release it immediately, and post a notice on "this page of
the WWW site"_bug. Each dated copy of Pizza.py contains all the
features and bug-fixes up to and including that version date. The
version date is printed to the screen and logfile every time you run
Pizza.py. It is also in the file src/version.h and in the Pizza.py
directory name created when you unpack a tarball.
If you browse the HTML or PDF doc pages on the Pizza.py WWW site, they
always describe the most current version of Pizza.py. :ulb,l
If you browse the HTML or PDF doc pages included in your tarball, they
describe the version you have. :ule,l
Pizza.py is a loosely integrated collection of tools written in
Python, many of which provide pre- and post-processing capability for
the "LAMMPS"_lammps molecular dynamics and "ChemCell"_cccell cell
simulator packages. There are tools to create input files, convert
between file formats, process log and dump files, create plots, and
visualize and animate simulation snapshots.
The name Pizza.py is meant to evoke the aroma of a collection of
"toppings" that the user can combine in different ways on a "crust" of
basic functionality, with Python as the "cheese" that glues everything
together.
The maintainer of Pizza.py is "Steve
Plimpton"_http://www.cs.sandia.gov/~sjplimp at "Sandia National
Laboratories"_sandia, a US Department of Energy ("DOE"_doe)
laboratory. Many of the tools were written by Matt Jones, a BYU
student who spent a summer at Sandia. The "Pizza.py WWW Site"_pws at
www.cs.sandia.gov/~sjplimp/pizza.html has more information about
Pizza.py and its uses.
:link(sandia,http://www.sandia.gov)
:link(bug,http://www.cs.sandia.gov/pizza/bug.html)
:link(sjp,http://www.cs.sandia.gov/~sjplimp)
:link(doe,http://www.doe.gov)
:link(lammps,http://www.cs.sandia.gov/~sjplimp/lammps.html)
:link(ccell,http://www.cs.sandia.gov/~sjplimp/chemcell.html)
:line
The Pizza.py documentation is organized into the following sections.
If you find errors or omissions in this manual or have suggestions for
useful information to add, please send an email to sjplimp@sandia.gov
so we can improve the Pizza.py documentation.
"PDF file"_Manual.pdf of the entire manual, generated by
"htmldoc"_http://www.easysw.com/htmldoc
"Introduction"_Section_intro.html :olb,l
1.1 "What is Pizza.py"_1_1 :ulb,b
1.2 "Open source distribution"_1_2 :b
1.3 "Acknowledgements"_1_3 :ule,b
"Installing Pizza.py"_Section_install.html :l
2.1 "Installing Python"_2_1 :ulb,b
2.2 "Running Pizza.py"_2_2 :b
2.3 "Setting up the DEFAULTS.py file"_2_3 :b
2.4 "Installing additional Python packages"_2_4 :b
2.5 "Installing other software"_2_5 :ule,b
"Basics of using Pizza.py"_Section_basics.html :l
3.1 "Python syntax"_3_1 :ulb,b
3.2 "Pizza.py command line arguments"_3_2 :b
3.3 "Pizza.py extensions to the Python interpreter"_3_3 :b
3.4 "Using Pizza.py tools"_3_4 :b
3.5 "Runnning Pizza.py and Python scripts"_3_5 :b
3.6 "Error messages"_3_6 :ule,b
"Tools within Pizza.py"_Section_tools.html :l
"Example scripts"_Section_examples.html :l
"Extending Pizza.py"_Section_extend.html :l
:ole
:line
List of tools in Pizza.py:
"animate.py"_animate.html; Animate a series of image files
"bdump.py"_bdump.html; Read LAMMPS dump local files with bond info
"cdata.py"_cdata.html; Read, write, manipulate "ChemCell"_ccell data files
"chain.py"_chain.html; Create bead-spring chains for LAMMPS input
"cfg.py"_cfg.html; Convert LAMMPS snapshots to CFG format
"clog.py"_clog.html; Read "ChemCell"_ccell log files and extract species data
"data.py"_data.html; Read, write, manipulate LAMMPS data files
"dump.py"_dump.html; Read, write, manipulate dump files and particle attributes
"ensight.py"_ensight.html; Convert LAMMPS snapshots to "Ensight"_ensight format
"gl.py"_gl.html; 3d interactive visualization via OpenGL
"gnu.py"_gnu.html; Create plots via "GnuPlot"_gnuplot plotting program
"histo.py"_histo.html; Particle density histogram from a dump
"image.py"_image.html; View and manipulate images
"ldump.py"_ldump.html; Read LAMMPS dump files with line info
"log.py"_log.html; Read LAMMPS log files and extract thermodynamic data
"matlab.py"_matlab.html; Create plots via "MatLab"_matlab numerical analysis program
"mdump.py"_mdump.html; Read, write, manipulate mesh dump files
"pair.py"_pair.html; Compute LAMMPS pairwise energies
"patch.py"_patch.html; Create patchy Lennard-Jones particles for LAMMPS input
"pdbfile.py"_pdbfile.html; Read, write PDB files in combo with LAMMPS snapshots
"plotview.py"_plotview.html; Plot multiple vectors from a data set
"rasmol.py"_rasmol.html; 3d visualization via "RasMol"_rasmol program
"raster.py"_raster.html; 3d visualization via "Raster3d"_raster3d program
"svg.py"_svg.html; 3d visualization via "SVG"_svg files
"tdump.py"_tdump.html; Read LAMMPS dump files with triangle info
"vcr.py"_vcr.html; VCR-style GUI for 3d interactive OpenGL visualization
"vec.py"_vec.html; Create numeric vectors from columns in file or list of vecs
"vtk.py"_vtk.html; Convert LAMMPS snapshots to VTK format
"vmd.py"_vmd.html; Wrapper on "VMD visualization package"_vmd
"xyz.py"_xyz.html; Convert LAMMPS snapshots to XYZ format :tb(s=;)
:link(gnuplot,http://www.gnuplot.info)
:link(matlab,http://www.mathworks.com)
:link(rasmol,http://www.openrasmol.org)
:link(raster3d,http://www.bmsc.washington.edu/raster3d/raster3d.html)
:link(svg,http://www.w3.org/Graphics/SVG)
:link(ensight,http://www.ensight.com)
:link(vmd,http://www.ks.uiuc.edu/Research/vmd)
:link(1_1,Section_intro.html#1_1)
:link(1_2,Section_intro.html#1_2)
:link(1_3,Section_intro.html#1_3)
:link(2_1,Section_install.html#2_1)
:link(2_2,Section_install.html#2_2)
:link(2_3,Section_install.html#2_3)
:link(2_4,Section_install.html#2_4)
:link(2_5,Section_install.html#2_5)
:link(3_1,Section_basics.html#3_1)
:link(3_2,Section_basics.html#3_2)
:link(3_3,Section_basics.html#3_3)
:link(3_4,Section_basics.html#3_4)
:link(3_5,Section_basics.html#3_5)
:link(3_6,Section_basics.html#3_6)

297
doc/Section_basics.html Normal file
View File

@ -0,0 +1,297 @@
<HTML>
<CENTER><A HREF = "Section_install.html">Previous Section</A> - <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> -
<A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A> - <A HREF = "Section_tools.html">Next
Section</A>
</CENTER>
<HR>
<H3>3. Basics of using Pizza.py
</H3>
<P>The <A HREF = "Section_install.txt">previous section</A> describes how to install
and run Pizza.py and the various software it uses. After Pizza.py has
started you should see a ">" prompt. The following sections describe
what comes next:
</P>
3.1 <A HREF = "#3_1">Python syntax</A><BR>
3.2 <A HREF = "#3_2">Pizza.py command line arguments</A><BR>
3.3 <A HREF = "#3_3">Pizza.py extensions to the Python interpreter</A><BR>
3.4 <A HREF = "#3_4">Using Pizza.py tools</A><BR>
3.5 <A HREF = "#3_5">Runnning Pizza.py and Python scripts</A><BR>
3.6 <A HREF = "#3_6">Error messages</A> <BR>
<HR>
<H4><A NAME = "3_1"></A>3.1 Python syntax
</H4>
<P>Aside from its tools, Pizza.py itself simply adds a bit of
functionality to the Python interpreter to enable it to more easily
launch shell commands and scripts and invoke its tools. Pizza.py's
">" prompt is different from Python's ">>>" prompt to indicate the
extra functionality is available, but you can type any Python command
you would type at the Python prompt.
</P>
<P>Python is a powerful scripting and programming language, similar in
scope and universality to Perl. This little Pizza.py manual cannot
attempt to teach you how to use Python, its syntax, or its rich set of
powerful built-in commands. If you only use the extra tools provided
by Pizza.py, you can think of Pizza.py as an application with a
self-contained set of commands. However, if you learn more about
Python, you will be able to write more powerful Pizza.py scripts,
access and manipulate data stored inside Pizza.py tools, or even add
your own commands and tools, which need not have anything to do with
LAMMPS or ChemCell.
</P>
<P>You can learn about Python at <A HREF = "python">www.python.org</A>. My most-used
Python book is <A HREF = "http://www.amazon.com/exec/obidos/tg/detail/-/0735709017/104-4868532-2659916?v=glance">Essential Python</A> by Dave Beazley which
assumes some programming experience but covers both the basics of
Python and its many powerful libraries in a well-written, concise
manner.
</P>
<HR>
<H4><A NAME = "3_2"></A>3.2 Pizza.py command line arguments
</H4>
<P>When running Pizza.py, several command-line options can be added
as switches, e.g.
</P>
<PRE>pizza.py switch args switch args ...
</PRE>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD > -s</TD><TD > silent (else print start-up help)</TD></TR>
<TR><TD > -t log dump raster</TD><TD > load only these tools</TD></TR>
<TR><TD > -x raster rasmol</TD><TD > load all tools except these</TD></TR>
<TR><TD > -f file arg1 arg2</TD><TD > run script file with args</TD></TR>
<TR><TD > -c "vec = range(100)"</TD><TD > run Python command</TD></TR>
<TR><TD > -q</TD><TD > quit (else interactive)
</TD></TR></TABLE></DIV>
<P>Switches can appear in any order and be used multiple times. The -f
scripts and -c commands are executed in the order they appear. Script
files are Python files which can contain Python or Pizza.py tool
commands. Pizza.py looks for script files in 3 places: your current
working directory, the pizza/scripts directory, and any extra
directories you list in the src/DEFAULTS.py file. This means you can
add your own scripts to pizza/scripts or to directories of your
choosing.
</P>
<P>The argument of the -c switch will typically need to be enclosed in
quotes to avoid being interpreted by the shell. This also allows
multiple Python commands to be separated by semi-colons, e.g.
</P>
<PRE>-c "a = range(100); print a"
</PRE>
<HR>
<H4><A NAME = "3_3"></A>3.3 Pizza.py extensions to the Python interpreter
</H4>
<P>As mentioned above, the standard Python syntax is extended a bit at
the Pizza.py ">" interactive prompt. These options were inspired by
the <A HREF = "http://www.idyll.org/~n8gray/code/index.html">LazyPython.py</A> code of Nathan Gray, which taught me how to
extend the Python interpreter. These are the short-cuts:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD > ?</TD><TD > print help message</TD></TR>
<TR><TD > ??</TD><TD > one-line for each tool and script</TD></TR>
<TR><TD > ? raster</TD><TD > list tool commands or script syntax</TD></TR>
<TR><TD > ?? energy.py</TD><TD > full documentation of tool or script </TD></TR>
<TR><TD > !ls -l</TD><TD > shell command</TD></TR>
<TR><TD > @cd ..</TD><TD > cd to a new directory</TD></TR>
<TR><TD > @log tmp.log</TD><TD > log all commands typed so far to file</TD></TR>
<TR><TD > @run block.py arg1 arg2</TD><TD > run script file with args</TD></TR>
<TR><TD > @time d = dump("*.dump")</TD><TD > time a command
</TD></TR></TABLE></DIV>
<P>Shell commands begun with a "!" can include the redirection operators
"<" or ">". The shell command "!cd" will not change directories
permanently; use the "@cd" short-cut instead. Any short-cut command
starting with "@" can be abbreviated with one or more letters.
E.g. "@r" is the same as "@run". The @log command requires that the
Python readline library be available on your system.
</P>
<P>Each of the above short-cuts can be performed by native Python
commands; they are just not as simple to type. Here is how several of
the short-cuts can be written in Python, which is what you need to do
in a script, since the above short-cuts only work at the Pizza.py
interactive prompt:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >Short-cut</TD><TD > Native Python</TD></TR>
<TR><TD >!ls -l</TD><TD > sys.command("ls -l")</TD></TR>
<TR><TD >@cd ..</TD><TD > os.chdir("..")</TD></TR>
<TR><TD >@run myfile.py</TD><TD > execfile("myfile.py")</TD></TR>
<TR><TD >CTRL-D</TD><TD > sys.exit()
</TD></TR></TABLE></DIV>
<HR>
<H4><A NAME = "3_4"></A>3.4 Using Pizza.py tools
</H4>
<P>The tools that Pizza.py adds to Python are each implemented as a
single Python class (e.g. dump, log, raster), so the first step in
using a tool is to create an instance of the class (an object). Each
class defines a set of methods (functions) that operate on the objects
you create and their associated data. Each method, including the
constructor, takes zero or more arguments, which may be previously
created objects. In practical terms, this means that you type
commands like this:
</P>
<PRE>d = dump("dump.*")
p = pdb("my.pdb",d)
p.many()
dnew = dump("dump.all")
</PRE>
<P>The first 2 commands create dump and pdb objects named "d" and "p"
respectively. The "d" and "p" are Python variable names; you could
use any names you wish: "dump12" or "Dump_mine" or whatever. The 3rd
line invokes the "many" method within the pdb class for the pdb object
"p". This method writes out a series of PDB files using the snapshots
in "d" which was passed to "p" when it was created. The final command
creates a new dump object "dnew" from another dump file. You can
create and manage as many objects (of the same or different classes)
simultaneously as you wish. If the last line assigned the object to
"d", the original dump object with the same name would be deleted by
Python.
</P>
<P>Various Pizza.py tools create temporary files as they operate. These
are all named tmp.*. Pizza.py does not clean up all of these files,
since they are sometimes useful to look at for debugging or other
purposes.
</P>
<P>Python syntax allows for powerful combinations of tools to be invoked
in one or a few commands. For example
</P>
<PRE>lg = log("log.*")
m = matlab()
plotview(lg,m)
</PRE>
<P>could be abbreviated as
</P>
<PRE>plotview(log("log.*"),matlab())
</PRE>
<P>With the -c command line switch, this one-liner could be specified
when Pizza.py is launched. This example also illustrates that created
objects (like the plotview object) do not need to be assigned to
variables if they will not be accessed in subsequent commands.
</P>
<HR>
<H4><A NAME = "3_5"></A>3.5 Running Pizza.py and Python scripts
</H4>
<P>A file containing Python and/or Pizza.py commands can be executed as a
script and arguments can be passed to it (if desired). The script can
be run in several different ways:
</P>
<P>(1) From the Pizza.py command line
</P>
<PRE>% pizza -f script.sample file.test 10 ...
</PRE>
<P>(2) From the Pizza.py interactive prompt
</P>
<PRE>> @run script.sample file.test 10 ...
</PRE>
<P>(3) From the Python command line
</P>
<PRE>% python -i script.sample file.test 10 ...
</PRE>
<P>(4) From a shell prompt with #!/usr/local/bin/python -i as 1st line of script
</P>
<PRE>% script.sample arg1 arg2 ...
</PRE>
<P>(5) From the Python interactive prompt
</P>
<PRE>>>> argv = <B>0,"file.test","10",...</B>
>>> execfile("script.sample")
</PRE>
<P>(6) As a nested script from within another Python or Pizza.py script file
</P>
<PRE>argv = <B>0,"file.test","10",...</B>
execfile("script.sample")
</PRE>
<P>The Pizza.py interpreter short-cut commands described
in the next section cannot be used in a script file.
</P>
<P>There are 2 additional issues to address in your script files.
</P>
<P>(A) First, if the script uses Pizza.py commands and you want to run it
from Python itself (methods 3,4,5,6), then your script should import
the necessary Pizza.py tools directly. E.g. if your script uses the
log and matlab tools, you would put these lines at the top:
</P>
<PRE>from log import log
from matlab import matlab
</PRE>
<P>This is OK to do even if the script will be run by Pizza.py since it
doesn't matter that Pizza.py already imported the tools. Note that if
you do this, you can then give your script file and the Python tool
*.py files it uses to someone who doesn't have Pizza.py and they can
run your script with their Python.
</P>
<P>(B) Second, if your script takes arguments and you want the same
script to run identically for all 6 methods, then you need to include
this line at the beginning of the script:
</P>
<PRE>if not globals().has_key("argv"): argv = sys.argv
</PRE>
<P>This will enable the arguments to be accessed in the script as
argv<B>1</B> for the 1st argument, argv<B>2</B> for the 2nd, etc.
</P>
<P>This works because in methods 3,4 Python stores the script arguments
in sys.argv and the script name in sys.argv<B>0</B>. The above line of
Python code copies sys.argv to argv. When Pizza.py runs the script
(methods 1,2) it loads the arguments directly into the "argv"
variable. Methods 5,6 load the arguments into argv explicitly before
executing the script via execfile(). In this case argv<B>0</B> is a dummy
argument to conform with the Python convention for sys.argv.
</P>
<P>Also note in methods 5,6 that all arguments such as "10" must be
strings even if they are numeric values, since this is the way they
are passed to the script in methods 1,2,3,4.
</P>
<P>As an example of the flexibility enabled by combining scripts,
arguments, and command-line options in Pizza.py, consider the 3-line
example of the previous sub-section. We modify the script as follows
and save it as logview.py:
</P>
<PRE>files = ' '.join(argv<B>1:</B>) # create one string from list of filenames
lg = log(files)
m = matlab()
plotview(lg,m)
</PRE>
<P>If an alias is defined in your shell start-up file, such as
</P>
<PRE>alias logview ~/pizza/src/pizza.py -f logview.py
</PRE>
<P>then you can type the following one-liner at the shell prompt to
invoke Pizza.py on the logview.py script with a list of files you
specfiy.
</P>
<PRE>% logview log.1 log.2 ...
</PRE>
<P>A set of plots and a control GUI will appear on your screen.
</P>
<HR>
<H4><A NAME = "3_6"></A>3.6 Error messages
</H4>
<P>If you mistype a Pizza.py or Python command or pass an invalid
argument to a tool method, an error message will be printed by Python.
Usually these will be self-explanatory. Sometimes they will point to
a line of code inside a tool which Python was unable to execute
successfully. This could be because you passed the wrong arguments to
the tool, the data the tool is operating on is invalid, or because
there's a bug in the tool. In the latter case, please figure out as
much as you can about the bug and email a description and the
necessary files to reproduce the bug in the simplest possible way to
sjplimp@sandia.gov.
</P>
</HTML>

286
doc/Section_basics.txt Normal file
View File

@ -0,0 +1,286 @@
"Previous Section"_Section_install.html - "Pizza.py WWW Site"_pws -
"Pizza.py Documentation"_pd - "Pizza.py Tools"_pt - "Next
Section"_Section_tools.html :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pt,Section_tools.html)
:line
3. Basics of using Pizza.py :h3
The "previous section"_Section_install.txt describes how to install
and run Pizza.py and the various software it uses. After Pizza.py has
started you should see a ">" prompt. The following sections describe
what comes next:
3.1 "Python syntax"_#3_1
3.2 "Pizza.py command line arguments"_#3_2
3.3 "Pizza.py extensions to the Python interpreter"_#3_3
3.4 "Using Pizza.py tools"_#3_4
3.5 "Runnning Pizza.py and Python scripts"_#3_5
3.6 "Error messages"_#3_6 :all(b)
:line
3.1 Python syntax :h4,link(3_1)
Aside from its tools, Pizza.py itself simply adds a bit of
functionality to the Python interpreter to enable it to more easily
launch shell commands and scripts and invoke its tools. Pizza.py's
">" prompt is different from Python's ">>>" prompt to indicate the
extra functionality is available, but you can type any Python command
you would type at the Python prompt.
Python is a powerful scripting and programming language, similar in
scope and universality to Perl. This little Pizza.py manual cannot
attempt to teach you how to use Python, its syntax, or its rich set of
powerful built-in commands. If you only use the extra tools provided
by Pizza.py, you can think of Pizza.py as an application with a
self-contained set of commands. However, if you learn more about
Python, you will be able to write more powerful Pizza.py scripts,
access and manipulate data stored inside Pizza.py tools, or even add
your own commands and tools, which need not have anything to do with
LAMMPS or ChemCell.
You can learn about Python at "www.python.org"_python. My most-used
Python book is "Essential Python"_beazley by Dave Beazley which
assumes some programming experience but covers both the basics of
Python and its many powerful libraries in a well-written, concise
manner.
:link(beazley,http://www.amazon.com/exec/obidos/tg/detail/-/0735709017/104-4868532-2659916?v=glance)
:line
3.2 Pizza.py command line arguments :h4,link(3_2)
When running Pizza.py, several command-line options can be added
as switches, e.g.
pizza.py switch args switch args ... :pre
-s, silent (else print start-up help)
-t log dump raster, load only these tools
-x raster rasmol, load all tools except these
-f file arg1 arg2, run script file with args
-c "vec = range(100)", run Python command
-q, quit (else interactive) :tb()
Switches can appear in any order and be used multiple times. The -f
scripts and -c commands are executed in the order they appear. Script
files are Python files which can contain Python or Pizza.py tool
commands. Pizza.py looks for script files in 3 places: your current
working directory, the pizza/scripts directory, and any extra
directories you list in the src/DEFAULTS.py file. This means you can
add your own scripts to pizza/scripts or to directories of your
choosing.
The argument of the -c switch will typically need to be enclosed in
quotes to avoid being interpreted by the shell. This also allows
multiple Python commands to be separated by semi-colons, e.g.
-c "a = range(100); print a" :pre
:line
3.3 Pizza.py extensions to the Python interpreter :h4,link(3_3)
As mentioned above, the standard Python syntax is extended a bit at
the Pizza.py ">" interactive prompt. These options were inspired by
the "LazyPython.py"_gray code of Nathan Gray, which taught me how to
extend the Python interpreter. These are the short-cuts:
?, print help message
??, one-line for each tool and script
? raster, list tool commands or script syntax
?? energy.py, full documentation of tool or script
!ls -l, shell command
@cd .., cd to a new directory
@log tmp.log, log all commands typed so far to file
@run block.py arg1 arg2, run script file with args
@time d = dump("*.dump"), time a command :tb()
:link(gray,http://www.idyll.org/~n8gray/code/index.html)
Shell commands begun with a "!" can include the redirection operators
"<" or ">". The shell command "!cd" will not change directories
permanently; use the "@cd" short-cut instead. Any short-cut command
starting with "@" can be abbreviated with one or more letters.
E.g. "@r" is the same as "@run". The @log command requires that the
Python readline library be available on your system.
Each of the above short-cuts can be performed by native Python
commands; they are just not as simple to type. Here is how several of
the short-cuts can be written in Python, which is what you need to do
in a script, since the above short-cuts only work at the Pizza.py
interactive prompt:
Short-cut, Native Python
!ls -l, sys.command("ls -l")
@cd .., os.chdir("..")
@run myfile.py, execfile("myfile.py")
CTRL-D, sys.exit() :tb()
:line
3.4 Using Pizza.py tools :h4,link(3_4)
The tools that Pizza.py adds to Python are each implemented as a
single Python class (e.g. dump, log, raster), so the first step in
using a tool is to create an instance of the class (an object). Each
class defines a set of methods (functions) that operate on the objects
you create and their associated data. Each method, including the
constructor, takes zero or more arguments, which may be previously
created objects. In practical terms, this means that you type
commands like this:
d = dump("dump.*")
p = pdb("my.pdb",d)
p.many()
dnew = dump("dump.all") :pre
The first 2 commands create dump and pdb objects named "d" and "p"
respectively. The "d" and "p" are Python variable names; you could
use any names you wish: "dump12" or "Dump_mine" or whatever. The 3rd
line invokes the "many" method within the pdb class for the pdb object
"p". This method writes out a series of PDB files using the snapshots
in "d" which was passed to "p" when it was created. The final command
creates a new dump object "dnew" from another dump file. You can
create and manage as many objects (of the same or different classes)
simultaneously as you wish. If the last line assigned the object to
"d", the original dump object with the same name would be deleted by
Python.
Various Pizza.py tools create temporary files as they operate. These
are all named tmp.*. Pizza.py does not clean up all of these files,
since they are sometimes useful to look at for debugging or other
purposes.
Python syntax allows for powerful combinations of tools to be invoked
in one or a few commands. For example
lg = log("log.*")
m = matlab()
plotview(lg,m) :pre
could be abbreviated as
plotview(log("log.*"),matlab()) :pre
With the -c command line switch, this one-liner could be specified
when Pizza.py is launched. This example also illustrates that created
objects (like the plotview object) do not need to be assigned to
variables if they will not be accessed in subsequent commands.
:line
3.5 Running Pizza.py and Python scripts :h4,link(3_5)
A file containing Python and/or Pizza.py commands can be executed as a
script and arguments can be passed to it (if desired). The script can
be run in several different ways:
(1) From the Pizza.py command line
% pizza -f script.sample file.test 10 ... :pre
(2) From the Pizza.py interactive prompt
> @run script.sample file.test 10 ... :pre
(3) From the Python command line
% python -i script.sample file.test 10 ... :pre
(4) From a shell prompt with #!/usr/local/bin/python -i as 1st line of script
% script.sample arg1 arg2 ... :pre
(5) From the Python interactive prompt
>>> argv = [0,"file.test","10",...]
>>> execfile("script.sample") :pre
(6) As a nested script from within another Python or Pizza.py script file
argv = [0,"file.test","10",...]
execfile("script.sample") :pre
The Pizza.py interpreter short-cut commands described
in the next section cannot be used in a script file.
There are 2 additional issues to address in your script files.
(A) First, if the script uses Pizza.py commands and you want to run it
from Python itself (methods 3,4,5,6), then your script should import
the necessary Pizza.py tools directly. E.g. if your script uses the
log and matlab tools, you would put these lines at the top:
from log import log
from matlab import matlab :pre
This is OK to do even if the script will be run by Pizza.py since it
doesn't matter that Pizza.py already imported the tools. Note that if
you do this, you can then give your script file and the Python tool
*.py files it uses to someone who doesn't have Pizza.py and they can
run your script with their Python.
(B) Second, if your script takes arguments and you want the same
script to run identically for all 6 methods, then you need to include
this line at the beginning of the script:
if not globals().has_key("argv"): argv = sys.argv :pre
This will enable the arguments to be accessed in the script as
argv[1] for the 1st argument, argv[2] for the 2nd, etc.
This works because in methods 3,4 Python stores the script arguments
in sys.argv and the script name in sys.argv[0]. The above line of
Python code copies sys.argv to argv. When Pizza.py runs the script
(methods 1,2) it loads the arguments directly into the "argv"
variable. Methods 5,6 load the arguments into argv explicitly before
executing the script via execfile(). In this case argv[0] is a dummy
argument to conform with the Python convention for sys.argv.
Also note in methods 5,6 that all arguments such as "10" must be
strings even if they are numeric values, since this is the way they
are passed to the script in methods 1,2,3,4.
As an example of the flexibility enabled by combining scripts,
arguments, and command-line options in Pizza.py, consider the 3-line
example of the previous sub-section. We modify the script as follows
and save it as logview.py:
files = ' '.join(argv[1:]) # create one string from list of filenames
lg = log(files)
m = matlab()
plotview(lg,m) :pre
If an alias is defined in your shell start-up file, such as
alias logview ~/pizza/src/pizza.py -f logview.py :pre
then you can type the following one-liner at the shell prompt to
invoke Pizza.py on the logview.py script with a list of files you
specfiy.
% logview log.1 log.2 ... :pre
A set of plots and a control GUI will appear on your screen.
:line
3.6 Error messages :h4,link(3_6)
If you mistype a Pizza.py or Python command or pass an invalid
argument to a tool method, an error message will be printed by Python.
Usually these will be self-explanatory. Sometimes they will point to
a line of code inside a tool which Python was unable to execute
successfully. This could be because you passed the wrong arguments to
the tool, the data the tool is operating on is invalid, or because
there's a bug in the tool. In the latter case, please figure out as
much as you can about the bug and email a description and the
necessary files to reproduce the bug in the simplest possible way to
sjplimp@sandia.gov.

57
doc/Section_examples.html Normal file
View File

@ -0,0 +1,57 @@
<HTML>
<CENTER><A HREF = "Section_tools.html">Previous Section</A> - <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> -
<A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A> - <A HREF = "Section_extend.html">Next
Section</A>
</CENTER>
<HR>
<H3>5. Example scripts
</H3>
<P>The Pizza.py distribution includes 2 sets of example scripts. A
listing of included scripts is given on the <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza/scripts.html">Pizza.py WWW
site</A>.
</P>
<P>(A) The examples directory has a README file and a variety of scripts.
For each tool in Pizza.py there is a test_tool.py script that invokes
the tool on a simple data set (from the files sub-directory) and
exercises various tool methods. These scripts are meant to illustrate
how the tool is used.
</P>
<P>Assuming pizza.py is in your path, each of the test scripts can be run
from within the examples directory by typing one of these lines (from
the shell or from within Pizza.py):
</P>
<PRE>% pizza.py -f test_animate.py
> @run test_animate.py
</PRE>
<P>The remaining scripts in the examples directory illustrate how to do
various tasks in Pizza.py. They are not meant to be generically
useful nor are they well documented. Rather they are illustrations of
how to do some specific task quickly and straightforwardly. Most of
these scripts are not meant to be run by other users, since their data
files are not included.
</P>
<P>(B) The scripts directory contains several scripts you may find useful
either to use directly or to modify to create a new script for your
purposes.
</P>
<P>The top of each script file describes its purpose and syntax. That
information can be be accessed from within Pizza.py by typing "??" or
"? name.py" or "?? name.py".
</P>
<P>As explained in <A HREF = "Section_basics.html#3_5">this section</A>, any file in
the scripts directory can be run from the directory where your data
lives, by typing a line appropriate to the script's syntax, e.g.
</P>
<PRE>% pizza.py -f movie.py svg 60 135 dump.protein from the shell
> @run movie.py svg 60 135 dump.protein from Pizza.py
</PRE>
</HTML>

52
doc/Section_examples.txt Normal file
View File

@ -0,0 +1,52 @@
"Previous Section"_Section_tools.html - "Pizza.py WWW Site"_pws -
"Pizza.py Documentation"_pd - "Pizza.py Tools"_pt - "Next
Section"_Section_extend.html :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pt,Section_tools.html)
:line
5. Example scripts :h3
The Pizza.py distribution includes 2 sets of example scripts. A
listing of included scripts is given on the "Pizza.py WWW
site"_scripts.
:link(scripts,http://www.cs.sandia.gov/~sjplimp/pizza/scripts.html)
(A) The examples directory has a README file and a variety of scripts.
For each tool in Pizza.py there is a test_tool.py script that invokes
the tool on a simple data set (from the files sub-directory) and
exercises various tool methods. These scripts are meant to illustrate
how the tool is used.
Assuming pizza.py is in your path, each of the test scripts can be run
from within the examples directory by typing one of these lines (from
the shell or from within Pizza.py):
% pizza.py -f test_animate.py
> @run test_animate.py :pre
The remaining scripts in the examples directory illustrate how to do
various tasks in Pizza.py. They are not meant to be generically
useful nor are they well documented. Rather they are illustrations of
how to do some specific task quickly and straightforwardly. Most of
these scripts are not meant to be run by other users, since their data
files are not included.
(B) The scripts directory contains several scripts you may find useful
either to use directly or to modify to create a new script for your
purposes.
The top of each script file describes its purpose and syntax. That
information can be be accessed from within Pizza.py by typing "??" or
"? name.py" or "?? name.py".
As explained in "this section"_Section_basics.html#3_5, any file in
the scripts directory can be run from the directory where your data
lives, by typing a line appropriate to the script's syntax, e.g.
% pizza.py -f movie.py svg 60 135 dump.protein from the shell
> @run movie.py svg 60 135 dump.protein from Pizza.py :pre

101
doc/Section_extend.html Normal file
View File

@ -0,0 +1,101 @@
<HTML>
<CENTER><A HREF = "Section_tools.html">Previous Section</A> - <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> -
<A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>6. Extending Pizza.py
</H3>
<P>Pizza.py can easily be extended in several ways:
</P>
<OL><LI>fix a bug
<LI>make a tool method faster or cleaner
<LI>add a new method or setting to a tool
<LI>add a new tool
<LI>add a generically useful script to the scripts dir
<LI>add a script that does something interesting to the examples dir
<LI>send a picture or movie you made with Pizza.py for the <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">WWW page</A>.
</OL>
<P>You might be able to do (2) because you're better with Python than we
are! Note that generally, we've opted for simplicity versus speed in
writing the tools, unless the operation is very costly. An example of
something I'd like to speed up is the reading of large dump files in
dump.py.
</P>
<P>Some of the ideas we've had for (3), but haven't gotten around to, are
listed at the top of the src/*.py files as ToDo items.
</P>
<P>If you think your addition will be useful to other Pizza.py users,
email it to sjplimp@sandia.gov and it can be added to the distribution
with an attribution to you, both in the source code and on the
<A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza/thanks.html">Pizza.py WWW site</A>.
</P>
<HR>
<P>Here are ideas to consider when creating new Pizza.py tools or
scripts:
</P>
<P>(1) For tools, your *.py file should contain a Python class with the
same name as the *.py file since it will be imported into Pizza.py
with a statement like
</P>
<PRE>from dump import dump
</PRE>
<P>(2) Your scripts can use methods from Pizza.py classes to make data
analysis easier. E.g. scripts can be written that use the dump tool
to read dump files, then use the iterator calls and vecs() method from
dump.py to loop over snapshots and extract lists of particles for
further computation. See the scripts and examples directories for
examples of this.
</P>
<P>(3) To flag an error in your script or tool and exit back to the
Pizza.py prompt, use a line like:
</P>
<PRE>raise StandardError,"error message"
</PRE>
<P>(4) Document your tool be defining the "oneline" and "docstr"
variables at the top of the file. This is what will be printed when
you type "? dump", for example.
</P>
<P>(5) If you intend your tool to interact with other Pizza.py tools, you
should follow the Pizza.py philosophy of having objects be passed as
arguments to the tool methods. If you're creating a tool that is
similar to an existing tool, but a different flavor (e.g. wrapping
another plotting package in addition to MatLab or GnuPlot), then try
to make the interface similar to the others so all the related tools
can be used interchangeably.
</P>
<P>(6) From the Pizza.py perspective, the difference between a script and
a tool is as follows. A script typically does a specific operation
(with or without arguments). E.g. process a dump file and compute a
quantity. A tool version of the same operation would allow it to
store internal state and persist, or to be packaged in a way that
other tools or scripts can create instances of it and call its
methods. From the Python perspective the code for the 2 cases may not
look very different. The tool version might just be some Python
variables and methods stuck inside a Python class, which is what a
Pizza.py tool basically is.
</P>
<P>(7) The various Pizza.py tools are mostly related to the "LAMMPS"
molecular dynamics or <A HREF = "http://www.cs.sandia.gov/~sjplimp/chemcell.html">ChemCell</A> cell simulator packages. But
of course you can write Pizza.py tools that have nothing to do with
LAMMPS or ChemCell. If you think they will still be of general
interest to Pizza.py users, you can send them to us to include in the
Pizza.py distribution. Or you can keep the top-level pizza.py file,
throw away the LAMMPS and ChemCell tool files, build your own toolkit
for whatever application you wish, and use or even distribute it
yourself. That's the open-source philosophy.
</P>
</HTML>

95
doc/Section_extend.txt Normal file
View File

@ -0,0 +1,95 @@
"Previous Section"_Section_tools.html - "Pizza.py WWW Site"_pws -
"Pizza.py Documentation"_pd - "Pizza.py Tools"_pt :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pt,Section_tools.html)
:line
6. Extending Pizza.py :h3
Pizza.py can easily be extended in several ways:
fix a bug
make a tool method faster or cleaner
add a new method or setting to a tool
add a new tool
add a generically useful script to the scripts dir
add a script that does something interesting to the examples dir
send a picture or movie you made with Pizza.py for the "WWW page"_pws. :ol
You might be able to do (2) because you're better with Python than we
are! Note that generally, we've opted for simplicity versus speed in
writing the tools, unless the operation is very costly. An example of
something I'd like to speed up is the reading of large dump files in
dump.py.
Some of the ideas we've had for (3), but haven't gotten around to, are
listed at the top of the src/*.py files as ToDo items.
If you think your addition will be useful to other Pizza.py users,
email it to sjplimp@sandia.gov and it can be added to the distribution
with an attribution to you, both in the source code and on the
"Pizza.py WWW site"_thanks.
:link(thanks,http://www.cs.sandia.gov/~sjplimp/pizza/thanks.html)
:line
Here are ideas to consider when creating new Pizza.py tools or
scripts:
(1) For tools, your *.py file should contain a Python class with the
same name as the *.py file since it will be imported into Pizza.py
with a statement like
from dump import dump :pre
(2) Your scripts can use methods from Pizza.py classes to make data
analysis easier. E.g. scripts can be written that use the dump tool
to read dump files, then use the iterator calls and vecs() method from
dump.py to loop over snapshots and extract lists of particles for
further computation. See the scripts and examples directories for
examples of this.
(3) To flag an error in your script or tool and exit back to the
Pizza.py prompt, use a line like:
raise StandardError,"error message" :pre
(4) Document your tool be defining the "oneline" and "docstr"
variables at the top of the file. This is what will be printed when
you type "? dump", for example.
(5) If you intend your tool to interact with other Pizza.py tools, you
should follow the Pizza.py philosophy of having objects be passed as
arguments to the tool methods. If you're creating a tool that is
similar to an existing tool, but a different flavor (e.g. wrapping
another plotting package in addition to MatLab or GnuPlot), then try
to make the interface similar to the others so all the related tools
can be used interchangeably.
(6) From the Pizza.py perspective, the difference between a script and
a tool is as follows. A script typically does a specific operation
(with or without arguments). E.g. process a dump file and compute a
quantity. A tool version of the same operation would allow it to
store internal state and persist, or to be packaged in a way that
other tools or scripts can create instances of it and call its
methods. From the Python perspective the code for the 2 cases may not
look very different. The tool version might just be some Python
variables and methods stuck inside a Python class, which is what a
Pizza.py tool basically is.
(7) The various Pizza.py tools are mostly related to the "LAMMPS"
molecular dynamics or "ChemCell"_ccell cell simulator packages. But
of course you can write Pizza.py tools that have nothing to do with
LAMMPS or ChemCell. If you think they will still be of general
interest to Pizza.py users, you can send them to us to include in the
Pizza.py distribution. Or you can keep the top-level pizza.py file,
throw away the LAMMPS and ChemCell tool files, build your own toolkit
for whatever application you wish, and use or even distribute it
yourself. That's the open-source philosophy.
:link(lammps,http://www.cs.sandia.gov/~sjplimp/lammps.html)
:link(ccell,http://www.cs.sandia.gov/~sjplimp/chemcell.html)

548
doc/Section_install.html Normal file
View File

@ -0,0 +1,548 @@
<HTML>
<CENTER><A HREF = "Section_intro.html">Previous Section</A> - <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> -
<A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A> - <A HREF = "Section_basics.html">Next
Section</A>
</CENTER>
<HR>
<H3>2. Installing Pizza.py
</H3>
<P>Unpack the Pizza.py distribution by typing the following:
</P>
<PRE>gunzip pizza.tar.gz
tar xvf pizza.tar
</PRE>
<P>The Pizza.py main directory should then contain the following
directories:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >README</TD><TD > initial instructions</TD></TR>
<TR><TD >LICENSE</TD><TD > the GNU open-source license</TD></TR>
<TR><TD >doc</TD><TD > HTML documentation for Pizza.py</TD></TR>
<TR><TD >examples</TD><TD > scripts and data sets that exercise Pizza.py tools</TD></TR>
<TR><TD >scripts</TD><TD > various Pizza.py script files</TD></TR>
<TR><TD >src</TD><TD > source code for Pizza.py and its tools
</TD></TR></TABLE></DIV>
<P>Because Python is an interpreted language, there is no need to compile
or "make" Pizza.py. You run Pizza.py by executing the src/pizza.py
file directly, as described below. However there are 3 issues to
consider: (a) you must have Python installed on your machine, (b) some
Pizza.py tools require your Python to be extended with additional
Python packages, and (c) some Pizza.py tools are wrappers on other
software which needs to be available on your system.
</P>
<P>If you don't plan to use a particular Pizza.py tool, you don't need to
install additional Python packages or other software it requires.
</P>
2.1 <A HREF = "#2_1">Installing Python</A><BR>
2.2 <A HREF = "#2_2">Running Pizza.py</A><BR>
2.3 <A HREF = "#2_3">Setting up the DEFAULTS.py file</A><BR>
2.4 <A HREF = "#2_4">Installing additional Python packages</A><BR>
2.5 <A HREF = "#2_5">Installing other software</A> <BR>
<P>Note that we cannot provide help on installing the various software
packages described here. If you have problems, you'll need to talk to
a local expert who can help you with your machine. If you find that
instructions on this page are incorrect or incomplete or you can
provide a better description of the install procedure, please send an
email to sjplimp@sandia.gov.
</P>
<HR>
<H4><A NAME = "2_1"></A>Installing Python
</H4>
<P>Python is open-source software available for Unix, Macintosh, and
Windows machines. If you have a Linux box or Mac it is probably
already installed. If the python executable is in your path, typing
"python" should give you a Python prompt ">>>" and tell you what
version you are running. Version 2.4 or newer is sufficiently current
to run Pizza.py, though older versions may work as well.
</P>
<P>If Python is not installed on your machine, go to
<A HREF = "http://www.python.org">www.python.org</A> to download a binary or
source-code version and then build and/or install it.
</P>
<P>On my Linux box, this was as easy as
</P>
<PRE>./configure; make; sudo make install
</PRE>
<P>To use the Pizza.py tools that have GUIs, you need to
insure your Python supports Tcl/Tk via the Tkinter module. This is
the case if you can type the following from your Python prompt:
</P>
<PRE>>>> import Tkinter
>>> Tkinter._test()
</PRE>
<P>If this fails, see further instructions below for Tkinter.
</P>
<P>IMPORTANT NOTE: If you are installing a new version of Python, read
the Tkinter section first, since it describes how to make sure the
Tcl/Tk and Togl libraries are installed. If you want to use the
Pizza.py tools that require them, you need to do this step first
before building Python.
</P>
<HR>
<H4><A NAME = "2_2"></A>Running Pizza.py
</H4>
<P>Typically Pizza.py should be run from the directory where your LAMMPS
or other data files are. Like any Python program, Pizza.py can be run
in one of 2 ways, by typing either
</P>
<PRE>python -i ~/pizza/src/pizza.py
~/pizza/src/pizza.py
</PRE>
<P>where the last argument is the full pathname of the pizza.py file.
</P>
<P>The -i switch leaves Python in interactive mode (instead of exiting)
after the pizza.py script is run. In the 2nd case, if the src dir is
in your path, just pizza.py could be typed. For the 2nd case, you
must also set src/pizza.py to be an executable file (chmod +x
pizza.py) and edit the 1st line of pizza.py to reflect where Python
lives on your system (find it by typing "which python"), e.g.
</P>
<PRE>#!/usr/local/bin/python -i
</PRE>
<P>Putting a definition like one of the following in your .cshrc file (or
equivalent syntax for other Unix shell start-up files) will let you
simply type "pizza" at the command-line to start Pizza.py.
</P>
<P>alias pizza python -i ~/pizza/src/pizza.py
alias pizza ~/pizza/src/pizza.py
</P>
<P>Pizza.py accepts several command-line options; they are described in
<A HREF = "Section_basics.html">this section</A> of the documentation.
</P>
<P>When Pizza.py starts, it reads a few values from the src/DEFAULTS.py
file (described below) and imports the *.py files from the src
directory as Python modules. These are the Pizza.py tools. Error
messages will be printed if your Python has not been extended with a
Python package that a tool requires. If you don't plan to use the
tool you can ignore the message, or exclude that tool via the
command-line switch "-x".
</P>
<P>Once all tools have been loaded and any initial scripts and commands
have been run (via command-line arguments) you should see the Pizza.py
">" prompt. From this point on, everything you type is a Python
command. Python interprets what you type, operates on your data, and
produces output or error messages, just as if you were typing in
response to Python's interactive prompt ">>>".
</P>
<P>You can also type special commands that have been added to the Python
interpreter by Pizza.py or commands that invoke Pizza.py tools. More
details about these options are explained in <A HREF = "Section_basics.html">this
section</A> of the documentation.
</P>
<P>As with Python, type Ctrl-D to exit Pizza.py at any time.
</P>
<HR>
<H4><A NAME = "2_3"></A>Setting up the DEFAULTS.py file
</H4>
<P>When Pizza.py starts it reads 3 values from the src/DEFAULTS.py file:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >PIZZA_TOOLS</TD><TD > directories that contain additional Pizza.py tools</TD></TR>
<TR><TD >PIZZA_SCRIPTS</TD><TD > directories that contain additional Pizza.py scripts</TD></TR>
<TR><TD >PIZZA_EXCLUDE</TD><TD > Python files that are not loaded, since they are not tools
</TD></TR></TABLE></DIV>
<P>These are designed to allow users to augment Pizza.py with their own
tools and scripts, which need not be stored in the directories of the
Pizza.py pacakge. Follow the instructions in the DEFAULTS.py file for
using these options.
</P>
<P>The DEFAULTS.py files also contains various variables that specify the
name and path of programs that Pizza.py tools will execute on your
system. In some cases the variables contain settings that are used by
these programs. Read the comments in the DEFAULTS.py file for more
information.
</P>
<P>The following table lists the keywords in the DEFAULTS.py, the program
or setting that will be used by default if the keyword line is
commented out, and the Pizza.py tools that use the keyword. If the
program is not in your path or you wish to use an alternate program or
setting, you must edit the DEFAULTS.py file accordingly. If you don't
plan to use any tool that needs the keyword, you can ignore its
setting.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >Keyword</TD><TD > Default Value</TD><TD > Purpose</TD><TD > Tools that Use it</TD></TR>
<TR><TD >DISPLAY</TD><TD > display</TD><TD > display image files (ImageMagick)</TD><TD > rasmol, raster, svg</TD></TR>
<TR><TD >CONVERT</TD><TD > convert</TD><TD > convert image files (ImageMagick)</TD><TD > image</TD></TR>
<TR><TD >MONTAGE</TD><TD > montage</TD><TD > montage image files (ImageMagick)</TD><TD > image</TD></TR>
<TR><TD >GNUPLOT</TD><TD > gnuplot</TD><TD > Gnu Plotting package</TD><TD > gnu</TD></TR>
<TR><TD >GNUTERM</TD><TD > x11</TD><TD > GnuPlot terminal</TD><TD > gnu</TD></TR>
<TR><TD >GUNZIP</TD><TD > gunzip</TD><TD > unzip a compressed *.gz file</TD><TD > dump, log</TD></TR>
<TR><TD >LABEL3D</TD><TD > label3d</TD><TD > put a label on a Raster3D image</TD><TD > raster</TD></TR>
<TR><TD >MATLAB</TD><TD > matlab</TD><TD > MatLab numerical analysis & plotting package</TD><TD > matlab</TD></TR>
<TR><TD >RASMOL</TD><TD > rasmol</TD><TD > RasMol molecular vizualization package</TD><TD > rasmol</TD></TR>
<TR><TD >RENDER</TD><TD > render</TD><TD > Raster3D vizualization rendering engine</TD><TD > raster </TD></TR>
<TR><TD >VMDNAME</TD><TD > vmd</TD><TD > VMD visualization package</TD><TD > vmd</TD></TR>
<TR><TD >VMDDIR</TD><TD > /usr/local/lib/vmd</TD><TD > VMD visualization package</TD><TD > vmd</TD></TR>
<TR><TD >VMDDEV</TD><TD > win</TD><TD > VMD visualization package</TD><TD > vmd</TD></TR>
<TR><TD >VMDARCH</TD><TD > LINUX</TD><TD > VMD visualization package</TD><TD > vmd
</TD></TR></TABLE></DIV>
<HR>
<H4><A NAME = "2_4"></A>Installing additional Python packages
</H4>
<P>This is the list of extra Python packages various Pizza.py tools
require. If a tool is not listed it requires no extra packages.
Instructions on where to find the Python extensions and how to install
them are listed below.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >Package </TD><TD > Tools that Use it</TD></TR>
<TR><TD >Numeric or Numpy </TD><TD > dump, mdump, bdump, ldump, tdump</TD></TR>
<TR><TD >pexpect </TD><TD > vmd</TD></TR>
<TR><TD >PIL </TD><TD > animate, gl, image</TD></TR>
<TR><TD >Pmw </TD><TD > image</TD></TR>
<TR><TD >PyOpenGL</TD><TD > gl, vcr</TD></TR>
<TR><TD >readline</TD><TD > Pizza.py itself</TD></TR>
<TR><TD >Tkinter </TD><TD > animate, image, plotview, vcr
</TD></TR></TABLE></DIV>
<HR>
<H4>Numeric or Numpy
</H4>
<P><A HREF = "http://numeric.scipy.org">Numeric</A> and its follow-on <A HREF = "numpy">NumPy</A> enables Python to
process vectors and arrays of numbers efficiently, both in terms of
memory and CPU speed. It's an extremely useful extension to have in
your Python if you do any numerical work on large data sets. Pizza.py
can use either Numeric or NumPy.
</P>
<P>If Numeric or NumPy is already installed in your Python, you should be
able to type one of the following without getting an error:
</P>
<PRE>>>> import Numeric
>>> import numpy
</PRE>
<P>Numeric can be downloaded from <A HREF = "http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=1351">this site</A> on SourceForge and
NumPy from <A HREF = "http://numeric.scipy.org">this site</A>. Numeric version 24.2 is fine for
Pizza.py as is a current version of NumPy. Once unpacked, you can
type the following from the Numeric or NumPy directories to install it
in your Python.
</P>
<PRE>sudo python setup.py install
</PRE>
<P>Note: on my Linux box, when Numeric installed itself under the Python
lib in /usr/local, it did not set all file permsissions correctly to
allow a user to import it. So I also needed to do this:
</P>
<PRE>sudo chmod -R 755 /usr/local/lib/python2.5/site-packages/Numeric
</PRE>
<HR>
<H4>pexpect
</H4>
<P><A HREF = "http://pypi.python.org/pypi/pexpect">Pexpect</A> in a pure Python
implementation of the Expect capability of the Tcl language. It
allows Python to send commands to another program, and handshake the
interaction between them, one command at a time.
</P>
<P>If pexpect is already installed in your Python, you should be able to
type the following without getting an error:
</P>
<PRE>>>> import pexpect
</PRE>
<P>Pexpect can be downloaded from <A HREF = "http://pypi.python.org/pypi/pexpect">this
site</A>. As of Nov 2010, Version
2.4 is fine. On my Linux box, this command installed it:
</P>
<PRE>sudo python setup.py install
</PRE>
<HR>
<H4>PIL
</H4>
<P>The PIL (<A HREF = "http://www.pythonware.com/products/pil">Python Imaging Library</A>) allows Python to read image
files, manipulate them, and convert between several common image
formats.
</P>
<P>If PIL is already installed in your Python, you should be able to type
the following without getting an error:
</P>
<PRE>>>> import Image,ImageTk
</PRE>
<P>PIL can be downloaded from <A HREF = "http://effbot.org/zone/pil-index.htm">this site</A>. As of July 2007,
Version 1.1.6 is fine. On my Linux box, this command installed it:
</P>
<PRE>sudo python setup.py install
</PRE>
<P>with a notice that Tkinter and ZLIB (PNG) support were enabled. If
you want the Pizza.py tools to recognize other image formats
(e.g. JPEG), then look at the README for further details, if the PIL
build did not find the correct libraries.
</P>
<HR>
<H4>Pmw
</H4>
<P>Pmw (<A HREF = "http://pmw.sourceforge.net">Python mega-widgets</A>) is a common Tkinter extension that
provides a host of more powerful GUI widgets.
</P>
<P>If Pmw is already installed in your Python, you should be able to type
the following without getting an error:
</P>
<PRE>>>> import Pmw
</PRE>
<P>Pmw can be downloaded from <A HREF = "http://pmw.sourceforge.net">this site</A>. As of July 2007, Version
1.2 is fine. Pmw is installed by putting its files in your Python's
site-packages directory. After unpacking the tarball and
naming the resulting dir "pmw", I installed it on my Linux
box as follows:
</P>
<PRE>sudo cp -r pmw /usr/local/lib/python2.5/site-packages/Pmw
sudo chmod -R 755 /usr/local/lib/python2.5/site-packages/Pmw
</PRE>
<HR>
<H4>PyOpenGL
</H4>
<P>The <A HREF = "http://pyopengl.sourceforge.net">PyOpenGL</A> package is a wrapper on the ubiquitous OpenGL
graphics library and allows a Python program to make graphics calls in
standard OpenGL syntax. It also includes Togl support for opening a
Tk OpenGL widget, assuming your Python has Tkinter intstalled and that
Tkinter was built with Togl (read on!). The Pizza.py tools that use
PyOpenGL require this capability.
</P>
<P>If PyOpenGL is already installed in your Python, you should be able to
type the following without getting an error:
</P>
<PRE>>>> import OpenGL
</PRE>
<P>If your PyOpenGL supports Togl, you should be able to type the
following without getting an error:
</P>
<PRE>>>> from OpenGL.Tk import *
>>> from OpenGL.GLUT import *
</PRE>
<P>PyOpenGL can be downloaded from <A HREF = "http://pyopengl.sourceforge.net">this site</A> on SourceForge.
You want the latest PyOpenGL release (not OpenGLContext). As of July
2007, Version 3.0.0a6 is what I used.
</P>
<P>IMPORTANT NOTE: I had many problems installing earlier versions of
PyOpenGL on various boxes. But the 3.0 release was much easier to
install on my Linux box, as outlined here. Note that version 3.0
requires Python 2.4 or later.
</P>
<P>IMPORTANT NOTE #2: By default, your Python may or may not have Tkinter
installed. Even if Tkinter is installed, it probably was not built
with Togl. If this is the case, you should install them first before
installing PyOpenGl, otherwise you will still get errors when you try
to use the Pizza.py tools that use PyOpenGL, because they require
Tkinter and Togl. See the Tkinter section below for instructions on
installing Tkinter and Togl in your Python.
</P>
<P>Installing 3.0 version of PyOpenGL requires the setuptools package be
part of your Python. As of July 2007, it can be downloaded from <A HREF = "http://peak.telecommunity.com/DevCenter/setuptools">this
site</A>. It is a single file, ez_setup.py, which can be
installed in your Python by typing:
</P>
<PRE>sudo python ez_setup.py
</PRE>
<P>Once setuptools and Tkinter and Togl are in place, installing PyOpenGL
on my Linux box was as simple as:
</P>
<PRE>sudo python setup.py install
</PRE>
<HR>
<H4>readline
</H4>
<P>The <A HREF = "http://cnswww.cns.cwru.edu/~chet/readline/rltop.html">readline</A> library is part of Python but is not supported
on all systems. If it works in your Python, then Pizza.py (and
Python) prompts are more shell-like and should support arrow keys,
Emacs-style editing, command history, etc. If you get an error "No
module named readline" when Pizza.py starts up, you can ignore it, or
comment out the line "import readline" in src/pizza.py.
</P>
<P>If readline is already installed in your Python, you should be able to
type the following without getting an error:
</P>
<PRE>>>> import readline
</PRE>
<P>The readline library can be downloaded from <A HREF = "http://cnswww.cns.cwru.edu/~chet/readline/rltop.html#Availability">this site</A>.
After building the library, I believe you then have to rebuild Python
itself.
</P>
<HR>
<H4>Tkinter
</H4>
<P>The Tkinter package is part of Python but is not always enabled when
Python is built, typically due to not finding the Tcl/Tk libraries.
If you can type the following without an error message in your Python,
then Tkinter is operational in your Python:
</P>
<PRE>>>> import Tkinter
>>> Tkinter._test()
</PRE>
<P>If this fails, you need to rebuild Python and either insure it finds
the Tcl/Tk libraries or build those libraries first as described here.
Since I wanted a more current Python then was installed with Linux on
my box, I download the latest Python (Python 2.5.1 as of July 2007)
and installed it under /usr/local.
</P>
<P>IMPORTANT NOTE: If you want to use any of the Pizza.py tools that use
PyOpenGL, you also need the Togl library. You should install it
before building the Tcl/Tk libraries which you then build before
re-building Python, as described here. Unfortunately, if Tkinter is
already in your Python but without Togl support, I think you need to
go thru these 3 steps in order.
</P>
<P>(1) To intstall Togl, download it from <A HREF = "http://togl.sourceforge.net">this site</A> on
SourceForge. As of July 2007, Version 1.7 is fine.
</P>
<P>After unpacking the tarball, installing it on my Linux box was
as simple as:
</P>
<PRE>./configure; make; sudo make install
</PRE>
<P>(2) To build Tck/Tk libraries with Togl support, go to <A HREF = "http://sourceforge.net/project/showfiles.php?group_id=10894">this
site</A> on SourceForce to download the latest versions of Tcl and
Tk.
</P>
<P>As of July 2007, I was unable to build version 8.4.15 on my Redhat
Linux box due to an odd error, but 8.4.7 built fine. After unpacking
the two tarballs I did the following:
</P>
<PRE>cd tcl8.4.7/unix
./configure; make; sudo make install
cd tk8.4.7/unix
./configure; make; sudo make install
</PRE>
<P>This build should find the Togl library previously installed under
/usr/local.
</P>
<P>(3) Now you can re-build Python and it should find the correct Tcl/Tk
libraries under /usr/local. Note that when you run ./configure as the
first step in building Python, it will tell you what it found for
Tcl/Tk.
</P>
<HR>
<H4><A NAME = "2_5"></A>Installing other software
</H4>
<P>Some Pizza.py tools invoke other software which must be installed on
your system for the tool to work. This is an alphabetic list of the
needed software. Except where noted, it is freely available for
download on the WWW. The Pizza.py tools that use this software are
listed above in <A HREF = "#2_3">this section</A>. To see if you already have the
software on your box, type "which command", e.g. "which display".
</P>
<H4>ImageMagick display, convert, montage commands
</H4>
<P>Several Pizza.py tools display image files. The ImageMagick "display"
program can be used for this purpose. Likewise, the ImageMagick
"convert" and "montage" comands are used by the image tool. The
ImageMagick toolkit can be downloaded from <A HREF = "http://www.imagemagick.org/script/index.php">this site</A> and
contains a variety of useful image conversion and manipulation
software.
</P>
<H4>GnuPlot
</H4>
<P>The Pizza.py gnu tool is a wrapper on the open-source GnuPlot program.
GnuPlot can be downloaded from <A HREF = "http://www.gnuplot.info">this site</A>.
</P>
<H4>Gunzip
</H4>
<P>Gunzip is invoked by Python to read compressed (*.gz) data and dump
files. It is almost certainly on your Unix system. If not if can be
downloaded from <A HREF = "http://www.gnu.org/software/gzip/gzip.html">this site</A>.
</P>
<H4>Label3d
</H4>
<P>The Pizza.py tool raster uses the label3d and render programs from the
Raster3d visualization package to produce high-quality ray-traced
images. See the description of "Render" below for information about
Raster3d.
</P>
<H4>MatLab
</H4>
<P>The Pizza.py matlab tool is a wrapper on MatLab which is a widely-used
commercial numerical analysis package that also produces nice plots.
Further information is available at <A HREF = "http://www.mathworks.com">the MathWorks WWW site</A>.
When MatLab is installed on your system and the appropriate
environment variables are set, the command "matlab" should launch the
program.
</P>
<H4>RasMol
</H4>
<P>The Pizza.py rasmol tool invokes the RasMol visualization package to
view molecular systems and produce nice images. RasMol can be
downloaded from <A HREF = "http://www.openrasmol.org">this site</A>, which is for the original
open-source version of RasMol, not the Protein Explorer derivative
version of RasMol.
</P>
<P>Note that when using RasMol on a Mac, you will need to launch X11
first (or run Pizza.py from an X11 xterm) to get RasMol to display
properly.
</P>
<H4>Render
</H4>
<P>The Pizza.py tool raster uses the render and label3d programs from the
Raster3d visualization package to produce high-quality ray-traced
images. Raster3d can be downloaded from <A HREF = "http://www.bmsc.washington.edu/raster3d/raster3d.html">this site</A>.
</P>
<P>For Macs, Raster3d is available for download via <A HREF = "http://fink.sourceforge.net/pdb/package.php/raster3d">Fink</A> as an
<A HREF = "http://fink.sourceforge.net/faq/usage-fink.php?phpLang=en#unstable">unstable package</A>.
</P>
<H4>VMD
</H4>
<P>The Pizza.py vmd tool is a simple wrapper on the <A HREF = "http://www.ks.uiuc.edu/Research/vmd">VMD visualization
package</A> which is a popular tool for visualizing the output of
molecular dynamics simulations. VMD can be downloaded from <A HREF = "http://www.ks.uiuc.edu/Research/vmd">this
site</A>.
</P>
</HTML>

531
doc/Section_install.txt Normal file
View File

@ -0,0 +1,531 @@
"Previous Section"_Section_intro.html - "Pizza.py WWW Site"_pws -
"Pizza.py Documentation"_pd - "Pizza.py Tools"_pt - "Next
Section"_Section_basics.html :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pt,Section_tools.html)
:line
2. Installing Pizza.py :h3
Unpack the Pizza.py distribution by typing the following:
gunzip pizza.tar.gz
tar xvf pizza.tar :pre
The Pizza.py main directory should then contain the following
directories:
README: initial instructions
LICENSE: the GNU open-source license
doc: HTML documentation for Pizza.py
examples: scripts and data sets that exercise Pizza.py tools
scripts: various Pizza.py script files
src: source code for Pizza.py and its tools :tb(s=:)
Because Python is an interpreted language, there is no need to compile
or "make" Pizza.py. You run Pizza.py by executing the src/pizza.py
file directly, as described below. However there are 3 issues to
consider: (a) you must have Python installed on your machine, (b) some
Pizza.py tools require your Python to be extended with additional
Python packages, and (c) some Pizza.py tools are wrappers on other
software which needs to be available on your system.
If you don't plan to use a particular Pizza.py tool, you don't need to
install additional Python packages or other software it requires.
2.1 "Installing Python"_#2_1
2.2 "Running Pizza.py"_#2_2
2.3 "Setting up the DEFAULTS.py file"_#2_3
2.4 "Installing additional Python packages"_#2_4
2.5 "Installing other software"_#2_5 :all(b)
Note that we cannot provide help on installing the various software
packages described here. If you have problems, you'll need to talk to
a local expert who can help you with your machine. If you find that
instructions on this page are incorrect or incomplete or you can
provide a better description of the install procedure, please send an
email to sjplimp@sandia.gov.
:line
Installing Python :h4,link(2_1)
Python is open-source software available for Unix, Macintosh, and
Windows machines. If you have a Linux box or Mac it is probably
already installed. If the python executable is in your path, typing
"python" should give you a Python prompt ">>>" and tell you what
version you are running. Version 2.4 or newer is sufficiently current
to run Pizza.py, though older versions may work as well.
If Python is not installed on your machine, go to
"www.python.org"_http://www.python.org to download a binary or
source-code version and then build and/or install it.
On my Linux box, this was as easy as
./configure; make; sudo make install :pre
To use the Pizza.py tools that have GUIs, you need to
insure your Python supports Tcl/Tk via the Tkinter module. This is
the case if you can type the following from your Python prompt:
>>> import Tkinter
>>> Tkinter._test() :pre
If this fails, see further instructions below for Tkinter.
IMPORTANT NOTE: If you are installing a new version of Python, read
the Tkinter section first, since it describes how to make sure the
Tcl/Tk and Togl libraries are installed. If you want to use the
Pizza.py tools that require them, you need to do this step first
before building Python.
:line
Running Pizza.py :h4,link(2_2)
Typically Pizza.py should be run from the directory where your LAMMPS
or other data files are. Like any Python program, Pizza.py can be run
in one of 2 ways, by typing either
python -i ~/pizza/src/pizza.py
~/pizza/src/pizza.py :pre
where the last argument is the full pathname of the pizza.py file.
The -i switch leaves Python in interactive mode (instead of exiting)
after the pizza.py script is run. In the 2nd case, if the src dir is
in your path, just pizza.py could be typed. For the 2nd case, you
must also set src/pizza.py to be an executable file (chmod +x
pizza.py) and edit the 1st line of pizza.py to reflect where Python
lives on your system (find it by typing "which python"), e.g.
#!/usr/local/bin/python -i :pre
Putting a definition like one of the following in your .cshrc file (or
equivalent syntax for other Unix shell start-up files) will let you
simply type "pizza" at the command-line to start Pizza.py.
alias pizza python -i ~/pizza/src/pizza.py
alias pizza ~/pizza/src/pizza.py
Pizza.py accepts several command-line options; they are described in
"this section"_Section_basics.html of the documentation.
When Pizza.py starts, it reads a few values from the src/DEFAULTS.py
file (described below) and imports the *.py files from the src
directory as Python modules. These are the Pizza.py tools. Error
messages will be printed if your Python has not been extended with a
Python package that a tool requires. If you don't plan to use the
tool you can ignore the message, or exclude that tool via the
command-line switch "-x".
Once all tools have been loaded and any initial scripts and commands
have been run (via command-line arguments) you should see the Pizza.py
">" prompt. From this point on, everything you type is a Python
command. Python interprets what you type, operates on your data, and
produces output or error messages, just as if you were typing in
response to Python's interactive prompt ">>>".
You can also type special commands that have been added to the Python
interpreter by Pizza.py or commands that invoke Pizza.py tools. More
details about these options are explained in "this
section"_Section_basics.html of the documentation.
As with Python, type Ctrl-D to exit Pizza.py at any time.
:line
Setting up the DEFAULTS.py file :h4,link(2_3)
When Pizza.py starts it reads 3 values from the src/DEFAULTS.py file:
PIZZA_TOOLS: directories that contain additional Pizza.py tools
PIZZA_SCRIPTS: directories that contain additional Pizza.py scripts
PIZZA_EXCLUDE: Python files that are not loaded, since they are not tools :tb(s=:)
These are designed to allow users to augment Pizza.py with their own
tools and scripts, which need not be stored in the directories of the
Pizza.py pacakge. Follow the instructions in the DEFAULTS.py file for
using these options.
The DEFAULTS.py files also contains various variables that specify the
name and path of programs that Pizza.py tools will execute on your
system. In some cases the variables contain settings that are used by
these programs. Read the comments in the DEFAULTS.py file for more
information.
The following table lists the keywords in the DEFAULTS.py, the program
or setting that will be used by default if the keyword line is
commented out, and the Pizza.py tools that use the keyword. If the
program is not in your path or you wish to use an alternate program or
setting, you must edit the DEFAULTS.py file accordingly. If you don't
plan to use any tool that needs the keyword, you can ignore its
setting.
Keyword: Default Value: Purpose: Tools that Use it
DISPLAY: display: display image files (ImageMagick): rasmol, raster, svg
CONVERT: convert: convert image files (ImageMagick): image
MONTAGE: montage: montage image files (ImageMagick): image
GNUPLOT: gnuplot: Gnu Plotting package: gnu
GNUTERM: x11: GnuPlot terminal: gnu
GUNZIP: gunzip: unzip a compressed *.gz file: dump, log
LABEL3D: label3d: put a label on a Raster3D image: raster
MATLAB: matlab: MatLab numerical analysis & plotting package: matlab
RASMOL: rasmol: RasMol molecular vizualization package: rasmol
RENDER: render: Raster3D vizualization rendering engine: raster
VMDNAME: vmd: VMD visualization package: vmd
VMDDIR: /usr/local/lib/vmd: VMD visualization package: vmd
VMDDEV: win: VMD visualization package: vmd
VMDARCH: LINUX: VMD visualization package: vmd :tb(s=:)
:line
Installing additional Python packages :h4,link(2_4)
This is the list of extra Python packages various Pizza.py tools
require. If a tool is not listed it requires no extra packages.
Instructions on where to find the Python extensions and how to install
them are listed below.
Package : Tools that Use it
Numeric or Numpy : dump, mdump, bdump, ldump, tdump
pexpect : vmd
PIL : animate, gl, image
Pmw : image
PyOpenGL: gl, vcr
readline: Pizza.py itself
Tkinter : animate, image, plotview, vcr :tb(s=:)
:line
Numeric or Numpy :h4
"Numeric"_numeric and its follow-on "NumPy"_numpy enables Python to
process vectors and arrays of numbers efficiently, both in terms of
memory and CPU speed. It's an extremely useful extension to have in
your Python if you do any numerical work on large data sets. Pizza.py
can use either Numeric or NumPy.
If Numeric or NumPy is already installed in your Python, you should be
able to type one of the following without getting an error:
>>> import Numeric
>>> import numpy :pre
Numeric can be downloaded from "this site"_numdown on SourceForge and
NumPy from "this site"_numeric. Numeric version 24.2 is fine for
Pizza.py as is a current version of NumPy. Once unpacked, you can
type the following from the Numeric or NumPy directories to install it
in your Python.
sudo python setup.py install :pre
Note: on my Linux box, when Numeric installed itself under the Python
lib in /usr/local, it did not set all file permsissions correctly to
allow a user to import it. So I also needed to do this:
sudo chmod -R 755 /usr/local/lib/python2.5/site-packages/Numeric :pre
:link(numeric,http://numeric.scipy.org)
:link(numdown,http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=1351)
:line
pexpect :h4
"Pexpect"_http://pypi.python.org/pypi/pexpect in a pure Python
implementation of the Expect capability of the Tcl language. It
allows Python to send commands to another program, and handshake the
interaction between them, one command at a time.
If pexpect is already installed in your Python, you should be able to
type the following without getting an error:
>>> import pexpect :pre
Pexpect can be downloaded from "this
site"_http://pypi.python.org/pypi/pexpect. As of Nov 2010, Version
2.4 is fine. On my Linux box, this command installed it:
sudo python setup.py install :pre
:line
PIL :h4
The PIL ("Python Imaging Library"_pil) allows Python to read image
files, manipulate them, and convert between several common image
formats.
:link(pil,http://www.pythonware.com/products/pil)
:link(pildown,http://effbot.org/zone/pil-index.htm)
If PIL is already installed in your Python, you should be able to type
the following without getting an error:
>>> import Image,ImageTk :pre
PIL can be downloaded from "this site"_pildown. As of July 2007,
Version 1.1.6 is fine. On my Linux box, this command installed it:
sudo python setup.py install :pre
with a notice that Tkinter and ZLIB (PNG) support were enabled. If
you want the Pizza.py tools to recognize other image formats
(e.g. JPEG), then look at the README for further details, if the PIL
build did not find the correct libraries.
:line
Pmw :h4
Pmw ("Python mega-widgets"_pmw) is a common Tkinter extension that
provides a host of more powerful GUI widgets.
:link(pmw,http://pmw.sourceforge.net)
If Pmw is already installed in your Python, you should be able to type
the following without getting an error:
>>> import Pmw :pre
Pmw can be downloaded from "this site"_pmw. As of July 2007, Version
1.2 is fine. Pmw is installed by putting its files in your Python's
site-packages directory. After unpacking the tarball and
naming the resulting dir "pmw", I installed it on my Linux
box as follows:
sudo cp -r pmw /usr/local/lib/python2.5/site-packages/Pmw
sudo chmod -R 755 /usr/local/lib/python2.5/site-packages/Pmw :pre
:line
PyOpenGL :h4
The "PyOpenGL"_pyopengl package is a wrapper on the ubiquitous OpenGL
graphics library and allows a Python program to make graphics calls in
standard OpenGL syntax. It also includes Togl support for opening a
Tk OpenGL widget, assuming your Python has Tkinter intstalled and that
Tkinter was built with Togl (read on!). The Pizza.py tools that use
PyOpenGL require this capability.
:link(pyopengl,http://pyopengl.sourceforge.net)
If PyOpenGL is already installed in your Python, you should be able to
type the following without getting an error:
>>> import OpenGL :pre
If your PyOpenGL supports Togl, you should be able to type the
following without getting an error:
>>> from OpenGL.Tk import *
>>> from OpenGL.GLUT import * :pre
PyOpenGL can be downloaded from "this site"_pyopengl on SourceForge.
You want the latest PyOpenGL release (not OpenGLContext). As of July
2007, Version 3.0.0a6 is what I used.
IMPORTANT NOTE: I had many problems installing earlier versions of
PyOpenGL on various boxes. But the 3.0 release was much easier to
install on my Linux box, as outlined here. Note that version 3.0
requires Python 2.4 or later.
IMPORTANT NOTE #2: By default, your Python may or may not have Tkinter
installed. Even if Tkinter is installed, it probably was not built
with Togl. If this is the case, you should install them first before
installing PyOpenGl, otherwise you will still get errors when you try
to use the Pizza.py tools that use PyOpenGL, because they require
Tkinter and Togl. See the Tkinter section below for instructions on
installing Tkinter and Togl in your Python.
Installing 3.0 version of PyOpenGL requires the setuptools package be
part of your Python. As of July 2007, it can be downloaded from "this
site"_setuptools. It is a single file, ez_setup.py, which can be
installed in your Python by typing:
sudo python ez_setup.py :pre
:link(setuptools,http://peak.telecommunity.com/DevCenter/setuptools)
Once setuptools and Tkinter and Togl are in place, installing PyOpenGL
on my Linux box was as simple as:
sudo python setup.py install :pre
:line
readline :h4
The "readline"_readline library is part of Python but is not supported
on all systems. If it works in your Python, then Pizza.py (and
Python) prompts are more shell-like and should support arrow keys,
Emacs-style editing, command history, etc. If you get an error "No
module named readline" when Pizza.py starts up, you can ignore it, or
comment out the line "import readline" in src/pizza.py.
If readline is already installed in your Python, you should be able to
type the following without getting an error:
>>> import readline :pre
The readline library can be downloaded from "this site"_readdown.
After building the library, I believe you then have to rebuild Python
itself.
:link(readline,http://cnswww.cns.cwru.edu/~chet/readline/rltop.html)
:link(readdown,http://cnswww.cns.cwru.edu/~chet/readline/rltop.html#Availability)
:line
Tkinter :h4
The Tkinter package is part of Python but is not always enabled when
Python is built, typically due to not finding the Tcl/Tk libraries.
If you can type the following without an error message in your Python,
then Tkinter is operational in your Python:
>>> import Tkinter
>>> Tkinter._test() :pre
If this fails, you need to rebuild Python and either insure it finds
the Tcl/Tk libraries or build those libraries first as described here.
Since I wanted a more current Python then was installed with Linux on
my box, I download the latest Python (Python 2.5.1 as of July 2007)
and installed it under /usr/local.
IMPORTANT NOTE: If you want to use any of the Pizza.py tools that use
PyOpenGL, you also need the Togl library. You should install it
before building the Tcl/Tk libraries which you then build before
re-building Python, as described here. Unfortunately, if Tkinter is
already in your Python but without Togl support, I think you need to
go thru these 3 steps in order.
(1) To intstall Togl, download it from "this site"_togl on
SourceForge. As of July 2007, Version 1.7 is fine.
:link(togl,http://togl.sourceforge.net)
After unpacking the tarball, installing it on my Linux box was
as simple as:
./configure; make; sudo make install :pre
(2) To build Tck/Tk libraries with Togl support, go to "this
site"_tcltk on SourceForce to download the latest versions of Tcl and
Tk.
:link(tcltk,http://sourceforge.net/project/showfiles.php?group_id=10894)
As of July 2007, I was unable to build version 8.4.15 on my Redhat
Linux box due to an odd error, but 8.4.7 built fine. After unpacking
the two tarballs I did the following:
cd tcl8.4.7/unix
./configure; make; sudo make install
cd tk8.4.7/unix
./configure; make; sudo make install :pre
This build should find the Togl library previously installed under
/usr/local.
(3) Now you can re-build Python and it should find the correct Tcl/Tk
libraries under /usr/local. Note that when you run ./configure as the
first step in building Python, it will tell you what it found for
Tcl/Tk.
:line
Installing other software :h4,link(2_5)
Some Pizza.py tools invoke other software which must be installed on
your system for the tool to work. This is an alphabetic list of the
needed software. Except where noted, it is freely available for
download on the WWW. The Pizza.py tools that use this software are
listed above in "this section"_#2_3. To see if you already have the
software on your box, type "which command", e.g. "which display".
ImageMagick display, convert, montage commands :h4
Several Pizza.py tools display image files. The ImageMagick "display"
program can be used for this purpose. Likewise, the ImageMagick
"convert" and "montage" comands are used by the image tool. The
ImageMagick toolkit can be downloaded from "this site"_imagemagick and
contains a variety of useful image conversion and manipulation
software.
:link(imagemagick,http://www.imagemagick.org/script/index.php)
GnuPlot :h4
The Pizza.py gnu tool is a wrapper on the open-source GnuPlot program.
GnuPlot can be downloaded from "this site"_gnuplot.
:link(gnuplot,http://www.gnuplot.info)
Gunzip :h4
Gunzip is invoked by Python to read compressed (*.gz) data and dump
files. It is almost certainly on your Unix system. If not if can be
downloaded from "this site"_gzip.
:link(gzip,http://www.gnu.org/software/gzip/gzip.html)
Label3d :h4
The Pizza.py tool raster uses the label3d and render programs from the
Raster3d visualization package to produce high-quality ray-traced
images. See the description of "Render" below for information about
Raster3d.
MatLab :h4
The Pizza.py matlab tool is a wrapper on MatLab which is a widely-used
commercial numerical analysis package that also produces nice plots.
Further information is available at "the MathWorks WWW site"_matlab.
When MatLab is installed on your system and the appropriate
environment variables are set, the command "matlab" should launch the
program.
:link(matlab,http://www.mathworks.com)
RasMol :h4
The Pizza.py rasmol tool invokes the RasMol visualization package to
view molecular systems and produce nice images. RasMol can be
downloaded from "this site"_rasmol, which is for the original
open-source version of RasMol, not the Protein Explorer derivative
version of RasMol.
:link(rasmol,http://www.openrasmol.org)
Note that when using RasMol on a Mac, you will need to launch X11
first (or run Pizza.py from an X11 xterm) to get RasMol to display
properly.
Render :h4
The Pizza.py tool raster uses the render and label3d programs from the
Raster3d visualization package to produce high-quality ray-traced
images. Raster3d can be downloaded from "this site"_raster.
:link(raster,http://www.bmsc.washington.edu/raster3d/raster3d.html)
For Macs, Raster3d is available for download via "Fink"_fink as an
"unstable package"_unstable.
:link(fink,http://fink.sourceforge.net/pdb/package.php/raster3d)
:link(unstable,http://fink.sourceforge.net/faq/usage-fink.php?phpLang=en#unstable)
VMD :h4
The Pizza.py vmd tool is a simple wrapper on the "VMD visualization
package"_vmd which is a popular tool for visualizing the output of
molecular dynamics simulations. VMD can be downloaded from "this
site"_vmd.
:link(vmd,http://www.ks.uiuc.edu/Research/vmd)

160
doc/Section_intro.html Normal file
View File

@ -0,0 +1,160 @@
<HTML>
<CENTER><A HREF = "Manual.html">Previous Section</A> - <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py
Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A> - <A HREF = "Section_install.html">Next
Section</A>
</CENTER>
<HR>
<H3>1. Introduction
</H3>
<P>These sections describe what Pizza.py is, what it means to be
open-source software, and acknowledge the funding and people who have
contributed to Pizza.py.
</P>
1.1 <A HREF = "#1_1">What is Pizza.Py</A><BR>
1.2 <A HREF = "#1_2">Open source distribution</A><BR>
1.3 <A HREF = "#1_3">Acknowledgements</A> <BR>
<HR>
<A NAME = "1_1"></A><H4>1.1 What is Pizza.py
</H4>
<P>Pizza.py is a loosely integrated collection of tools, many of which
provide pre- and post-processing capabilities for the <A HREF = "http://www.cs.sandia.gov/~sjplimp/lammps.html">LAMMPS</A>
molecular dynamics and <A HREF = "http://www.cs.sandia.gov/~sjplimp/chemcell.html">ChemCell</A> cell simulator packages.
</P>
<P>There are tools to create input files, convert between file formats to
connect to other codes, process log and dump files, plot output, and
visualize and animate simulation snapshots.
</P>
<P>Python is used in Pizza.py in 3 ways:
</P>
<UL><LI>to provide an interactive and scripting interface to the tools
<LI>as a language for writing tools
<LI>to wrap existing stand-alone codes
</UL>
<P>Python makes it easy for users of Pizza.py to:
</P>
<UL><LI>experiment with tools interactively
<LI>automate tasks as script files of commands
<LI>extend tools or create new ones
</UL>
<P>The topmost level of Pizza.py adds a modest bit of functionality to
the Python interpreter to make it easier to invoke tools and pass data
between them. As such, Python is an ideal "framework" or "glue"
language that enables various tools to be hooked together, while also
providing a rich programming environment of its own.
</P>
<HR>
<A NAME = "1_2"></A><H4>1.2 Open source distribution
</H4>
<P>Pizza.py comes with no warranty of any kind. As each source file
states in its header, it is distributed free-of-charge, under the
terms of the <A HREF = "http://www.gnu.org/copyleft/gpl.html">GNU Public License</A> (GPL). This is often referred
to as open-source distribution - see <A HREF = "http://www.gnu.org">www.gnu.org</A> or
<A HREF = "http://www.opensource.org">www.opensource.org</A> for more details. The legal text of
the GPL is in the LICENSE file that is included in the Pizza.py
distribution.
</P>
<P>Here is a summary of what the GPL means for Pizza.py users:
</P>
<P>(1) Anyone is free to use, modify, or extend Pizza.py in any way they
choose, including for commercial purposes.
</P>
<P>(2) If you distribute a modified version of Pizza.py, it must remain
open-source, meaning you distribute it under the terms of the GPL.
You should clearly annotate such a code as a derivative version of
Pizza.py.
</P>
<P>(3) If you release any code that includes Pizza.py source code, then
it must also be open-sourced, meaning you distribute it under the
terms of the GPL.
</P>
<P>(4) If you give Pizza.py to someone else, the GPL LICENSE file and
source file headers (including the GPL notices) should remain part of
the code.
</P>
<P>In the spirit of an open-source code, these are various ways you can
contribute to making Pizza.py better. You can send email to
sjplimp@sandia.gov on any of these items.
</P>
<UL><LI>If you write a Pizza.py script that is generally useful or illustrates
how to do something cool with Pizza.py, it can be added to the
Pizza.py distribution. Ditto for a picture or movie that can be added
to the <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW site</A>.
<LI>If you add a new method to one of the tools or create a new tool that
is useful for Pizza.py or LAMMPS or ChemCell users, it can be added to
the Pizza.py distribution. See the ToDo list at the beginning of the
src/*.py files for features that haven't yet been implemented.
<LI>If you find a bug, report it.
<LI>Report if you find an error or omission in the <A HREF = "Manual.html">Pizza.py
documentation</A> or on the <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A>, or have a
suggestion for something to clarify or include.
<LI>Point prospective users to the <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> or link to it
from your WWW site.
</UL>
<HR>
<H4><A NAME = "1_3"></A>1.3 Acknowledgements
</H4>
<P>Pizza.py has been developed at <A HREF = "http://www.sandia.gov">Sandia National Laboratories</A>
which is a multiprogram laboratory operated by Sandia Corporation, a
Lockheed Martin Company, for the United States Department of Energy's
National Nuclear Security Administration under contract
DE-AC04-94AL85000.
</P>
<P>Funding for Pizza.py development has come from the US Department of
Energy (<A HREF = "http://www.doe.gov">DOE</A>), through its LDRD and Genomes-to-Life programs.
The latter effort has been funded by DOE's <A HREF = "http://www.sc.doe.gov/ascr/home.html">OASCR</A> and
<A HREF = "http://www.er.doe.gov/production/ober/ober_top.html">OBER</A> offices as part of the US Department of Energy's
Genomics:GTL program (<A HREF = "http://www.doegenomestolife.org">www.doegenomestolife.org</A>) under the
<A HREF = "http://www.genomes2life.org">project</A>, "Carbon Sequestration in Synechococcus Sp.: From
Molecular Machines to Hierarchical Modeling".
</P>
<P>The maintainer of Pizza.py is <A HREF = "http://www.cs.sandia.gov/~sjplimp">Steve Plimpton</A>.
</P>
<P>Matt Jones, a BYU student who was a summer intern at Sandia, wrote
several of the coolest tools in Pizza.py and about half the code in
the initial version.
</P>
<P>Others who have written tools or scripts that are part of the Pizza.py
distribution are listed on the <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza/thanks.html">Pizza.py WWW site</A>.
</P>
</HTML>

147
doc/Section_intro.txt Normal file
View File

@ -0,0 +1,147 @@
"Previous Section"_Manual.html - "Pizza.py WWW Site"_pws - "Pizza.py
Documentation"_pd - "Pizza.py Tools"_pt - "Next
Section"_Section_install.html :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pt,Section_tools.html)
:line
1. Introduction :h3
These sections describe what Pizza.py is, what it means to be
open-source software, and acknowledge the funding and people who have
contributed to Pizza.py.
1.1 "What is Pizza.Py"_#1_1
1.2 "Open source distribution"_#1_2
1.3 "Acknowledgements"_#1_3 :all(b)
:line
1.1 What is Pizza.py :link(1_1),h4
Pizza.py is a loosely integrated collection of tools, many of which
provide pre- and post-processing capabilities for the "LAMMPS"_lammps
molecular dynamics and "ChemCell"_ccell cell simulator packages.
:link(lammps,http://www.cs.sandia.gov/~sjplimp/lammps.html)
:link(ccell,http://www.cs.sandia.gov/~sjplimp/chemcell.html)
There are tools to create input files, convert between file formats to
connect to other codes, process log and dump files, plot output, and
visualize and animate simulation snapshots.
Python is used in Pizza.py in 3 ways:
to provide an interactive and scripting interface to the tools
as a language for writing tools
to wrap existing stand-alone codes :ul
Python makes it easy for users of Pizza.py to:
experiment with tools interactively
automate tasks as script files of commands
extend tools or create new ones :ul
The topmost level of Pizza.py adds a modest bit of functionality to
the Python interpreter to make it easier to invoke tools and pass data
between them. As such, Python is an ideal "framework" or "glue"
language that enables various tools to be hooked together, while also
providing a rich programming environment of its own.
:line
1.2 Open source distribution :link(1_2),h4
Pizza.py comes with no warranty of any kind. As each source file
states in its header, it is distributed free-of-charge, under the
terms of the "GNU Public License"_gnu (GPL). This is often referred
to as open-source distribution - see "www.gnu.org"_gnuorg or
"www.opensource.org"_opensource for more details. The legal text of
the GPL is in the LICENSE file that is included in the Pizza.py
distribution.
:link(gnu,http://www.gnu.org/copyleft/gpl.html)
:link(gnuorg,http://www.gnu.org)
:link(opensource,http://www.opensource.org)
Here is a summary of what the GPL means for Pizza.py users:
(1) Anyone is free to use, modify, or extend Pizza.py in any way they
choose, including for commercial purposes.
(2) If you distribute a modified version of Pizza.py, it must remain
open-source, meaning you distribute it under the terms of the GPL.
You should clearly annotate such a code as a derivative version of
Pizza.py.
(3) If you release any code that includes Pizza.py source code, then
it must also be open-sourced, meaning you distribute it under the
terms of the GPL.
(4) If you give Pizza.py to someone else, the GPL LICENSE file and
source file headers (including the GPL notices) should remain part of
the code.
In the spirit of an open-source code, these are various ways you can
contribute to making Pizza.py better. You can send email to
sjplimp@sandia.gov on any of these items.
If you write a Pizza.py script that is generally useful or illustrates
how to do something cool with Pizza.py, it can be added to the
Pizza.py distribution. Ditto for a picture or movie that can be added
to the "Pizza.py WWW site"_pws. :ulb,l
If you add a new method to one of the tools or create a new tool that
is useful for Pizza.py or LAMMPS or ChemCell users, it can be added to
the Pizza.py distribution. See the ToDo list at the beginning of the
src/*.py files for features that haven't yet been implemented. :l
If you find a bug, report it. :l
Report if you find an error or omission in the "Pizza.py
documentation"_pd or on the "Pizza.py WWW Site"_pws, or have a
suggestion for something to clarify or include. :l
Point prospective users to the "Pizza.py WWW Site"_pws or link to it
from your WWW site. :ule,l
:line
1.3 Acknowledgements :h4,link(1_3)
Pizza.py has been developed at "Sandia National Laboratories"_sandia
which is a multiprogram laboratory operated by Sandia Corporation, a
Lockheed Martin Company, for the United States Department of Energy's
National Nuclear Security Administration under contract
DE-AC04-94AL85000.
Funding for Pizza.py development has come from the US Department of
Energy ("DOE"_doe), through its LDRD and Genomes-to-Life programs.
The latter effort has been funded by DOE's "OASCR"_oascr and
"OBER"_ober offices as part of the US Department of Energy's
Genomics:GTL program ("www.doegenomestolife.org"_gtl) under the
"project"_ourgtl, "Carbon Sequestration in Synechococcus Sp.: From
Molecular Machines to Hierarchical Modeling".
:link(sandia,http://www.sandia.gov)
:link(doe,http://www.doe.gov)
:link(gtl,http://www.doegenomestolife.org)
:link(ourgtl,http://www.genomes2life.org)
:link(oascr,http://www.sc.doe.gov/ascr/home.html)
:link(ober,http://www.er.doe.gov/production/ober/ober_top.html)
The maintainer of Pizza.py is "Steve Plimpton"_sjp.
:link(sjp,http://www.cs.sandia.gov/~sjplimp)
Matt Jones, a BYU student who was a summer intern at Sandia, wrote
several of the coolest tools in Pizza.py and about half the code in
the initial version.
Others who have written tools or scripts that are part of the Pizza.py
distribution are listed on the "Pizza.py WWW site"_authors.
:link(authors,http://www.cs.sandia.gov/~sjplimp/pizza/thanks.html)

101
doc/Section_tools.html Normal file
View File

@ -0,0 +1,101 @@
<HTML>
<CENTER><A HREF = "Section_basics.html">Previous Section</A> - <A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> -
<A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A> - <A HREF = "Section_examples.html">Next
Section</A>
</CENTER>
<HR>
<H3>4. Tools within Pizza.py
</H3>
<P><A HREF = "Section_basics.html#3_4">Th previous section</A> describes how Pizza.py
tools are used in Pizza.py.
</P>
<P>Help on the syntax for invoking a tool and using its methods and
settings can be accessed interactively within Pizza.py itself by
typing "? tool" or "?? tool". Typing "??" gives a one-line
description of each tool.
</P>
<P>These are the different categories of Pizza.py tools:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >LAMMPS in/out files</TD><TD > chain, data, dump, log, patch, bdump, ldump, tdump</TD></TR>
<TR><TD >ChemCell in/out files</TD><TD > cdata, clog, dump</TD></TR>
<TR><TD >Visualization</TD><TD > gl, rasmol, raster, svg, vmd</TD></TR>
<TR><TD >File conversion</TD><TD > cfg, ensight, pdbfile, vtk, xyz</TD></TR>
<TR><TD >GUI wrappers</TD><TD > animate, image, plotview, vcr</TD></TR>
<TR><TD >Plotting</TD><TD > gnu, matlab</TD></TR>
<TR><TD >Miscellaneous</TD><TD > histo, mdump, pair, vec
</TD></TR></TABLE></DIV>
<P>Within the plotting and viz categories, individual tools share many
common methods, so the tools can often be used interchangeably. For
example, the same script can produce an animation using either
Raster3d or SVG to generate the movie frames, by simply changing the
line that creates the visualizer object, or by passing the object into
the script as an argument.
</P>
<P>This is the complete list of tools in Pizza.py; the link is to each
tool's documentation page.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD ><A HREF = "animate.html">animate.py</A></TD><TD > Animate a series of image files</TD></TR>
<TR><TD ><A HREF = "bdump.html">bdump.py</A></TD><TD > Read LAMMPS dump local files with bond info</TD></TR>
<TR><TD ><A HREF = "data.html">cdata.py</A></TD><TD > Read, write, manipulate <A HREF = "http://www.cs.sandia.gov/~sjplimp/cell.html">Chemcell</A> data files</TD></TR>
<TR><TD ><A HREF = "chain.html">chain.py</A></TD><TD > Create bead-spring chains for LAMMPS input</TD></TR>
<TR><TD ><A HREF = "cfg.html">cfg.py</A></TD><TD > Convert LAMMPS snapshots to CFG format</TD></TR>
<TR><TD ><A HREF = "clog.html">clog.py</A></TD><TD > Read <A HREF = "http://www.cs.sandia.gov/~sjplimp/cell.html">ChemCell</A> log files and extract species data</TD></TR>
<TR><TD ><A HREF = "data.html">data.py</A></TD><TD > Read, write, manipulate LAMMPS data files</TD></TR>
<TR><TD ><A HREF = "dump.html">dump.py</A></TD><TD > Read, write, manipulate dump files and particle attributes</TD></TR>
<TR><TD ><A HREF = "ensight.html">ensight.py</A></TD><TD > Convert LAMMPS snapshots to <A HREF = "http://www.ensight.com">Ensight</A> format</TD></TR>
<TR><TD ><A HREF = "gl.html">gl.py</A></TD><TD > 3d interactive visualization via OpenGL</TD></TR>
<TR><TD ><A HREF = "gnu.html">gnu.py</A></TD><TD > Create plots via <A HREF = "http://www.gnuplot.info">GnuPlot</A> plotting program</TD></TR>
<TR><TD ><A HREF = "histo.html">histo.py</A></TD><TD > Particle density histogram from a dump</TD></TR>
<TR><TD ><A HREF = "image.html">image.py</A></TD><TD > View and manipulate images</TD></TR>
<TR><TD ><A HREF = "ldump.html">ldump.py</A></TD><TD > Read LAMMPS dump files with line info</TD></TR>
<TR><TD ><A HREF = "log.html">log.py</A></TD><TD > Read LAMMPS log files and extract thermodynamic data</TD></TR>
<TR><TD ><A HREF = "matlab.html">matlab.py</A></TD><TD > Create plots via <A HREF = "http://www.mathworks.com">MatLab</A> numerical analysis program</TD></TR>
<TR><TD ><A HREF = "mdump.html">mdump.py</A></TD><TD > Read, write, manipulate mesh dump files</TD></TR>
<TR><TD ><A HREF = "pair.html">pair.py</A></TD><TD > Compute LAMMPS pairwise energies</TD></TR>
<TR><TD ><A HREF = "patch.html">patch.py</A></TD><TD > Create patchy Lennard-Jones particles for LAMMPS input</TD></TR>
<TR><TD ><A HREF = "pdbfile.html">pdbfile.py</A></TD><TD > Read, write PDB files in combo with LAMMPS snapshots</TD></TR>
<TR><TD ><A HREF = "plotview.html">plotview.py</A></TD><TD > Plot multiple vectors from a data set</TD></TR>
<TR><TD ><A HREF = "rasmol.html">rasmol.py</A></TD><TD > 3d visualization via <A HREF = "http://www.openrasmol.org">RasMol</A> program</TD></TR>
<TR><TD ><A HREF = "raster.html">raster.py</A></TD><TD > 3d visualization via <A HREF = "http://www.bmsc.washington.edu/raster3d/raster3d.html">Raster3d</A> program</TD></TR>
<TR><TD ><A HREF = "svg.html">svg.py</A></TD><TD > 3d visualization via <A HREF = "http://www.w3.org/Graphics/SVG">SVG</A> files</TD></TR>
<TR><TD ><A HREF = "tdump.html">tdump.py</A></TD><TD > Read LAMMPS dump files with triangle info</TD></TR>
<TR><TD ><A HREF = "vcr.html">vcr.py</A></TD><TD > VCR-style GUI for 3d interactive OpenGL visualization</TD></TR>
<TR><TD ><A HREF = "vec.html">vec.py</A></TD><TD > Create numeric vectors from columns in file or list of vecs</TD></TR>
<TR><TD ><A HREF = "vtk.html">vtk.py</A></TD><TD > Convert LAMMPS snapshots to VTK format</TD></TR>
<TR><TD ><A HREF = "vmd.html">vmd.py</A></TD><TD > Wrapper on <A HREF = "http://www.ks.uiuc.edu/Research/vmd">VMD visualization package</A></TD></TR>
<TR><TD ><A HREF = "xyz.html">xyz.py</A></TD><TD > Convert LAMMPS snapshots to XYZ format
</TD></TR></TABLE></DIV>
<P>This diagram represents the different ways tools can be interconnected
by Pizza.py. Tools within the same red box are tools that are
(roughly) interchangeable.
</P>
<CENTER><IMG SRC = "tools.jpg">
</CENTER>
</HTML>

85
doc/Section_tools.txt Normal file
View File

@ -0,0 +1,85 @@
"Previous Section"_Section_basics.html - "Pizza.py WWW Site"_pws -
"Pizza.py Documentation"_pd - "Pizza.py Tools"_pt - "Next
Section"_Section_examples.html :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pt,Section_tools.html)
:line
4. Tools within Pizza.py :h3
"Th previous section"_Section_basics.html#3_4 describes how Pizza.py
tools are used in Pizza.py.
Help on the syntax for invoking a tool and using its methods and
settings can be accessed interactively within Pizza.py itself by
typing "? tool" or "?? tool". Typing "??" gives a one-line
description of each tool.
These are the different categories of Pizza.py tools:
LAMMPS in/out files: chain, data, dump, log, patch, bdump, ldump, tdump
ChemCell in/out files: cdata, clog, dump
Visualization: gl, rasmol, raster, svg, vmd
File conversion: cfg, ensight, pdbfile, vtk, xyz
GUI wrappers: animate, image, plotview, vcr
Plotting: gnu, matlab
Miscellaneous: histo, mdump, pair, vec :tb(s=:)
Within the plotting and viz categories, individual tools share many
common methods, so the tools can often be used interchangeably. For
example, the same script can produce an animation using either
Raster3d or SVG to generate the movie frames, by simply changing the
line that creates the visualizer object, or by passing the object into
the script as an argument.
This is the complete list of tools in Pizza.py; the link is to each
tool's documentation page.
"animate.py"_animate.html; Animate a series of image files
"bdump.py"_bdump.html; Read LAMMPS dump local files with bond info
"cdata.py"_data.html; Read, write, manipulate "Chemcell"_ccell data files
"chain.py"_chain.html; Create bead-spring chains for LAMMPS input
"cfg.py"_cfg.html; Convert LAMMPS snapshots to CFG format
"clog.py"_clog.html; Read "ChemCell"_ccell log files and extract species data
"data.py"_data.html; Read, write, manipulate LAMMPS data files
"dump.py"_dump.html; Read, write, manipulate dump files and particle attributes
"ensight.py"_ensight.html; Convert LAMMPS snapshots to "Ensight"_ensight format
"gl.py"_gl.html; 3d interactive visualization via OpenGL
"gnu.py"_gnu.html; Create plots via "GnuPlot"_gnuplot plotting program
"histo.py"_histo.html; Particle density histogram from a dump
"image.py"_image.html; View and manipulate images
"ldump.py"_ldump.html; Read LAMMPS dump files with line info
"log.py"_log.html; Read LAMMPS log files and extract thermodynamic data
"matlab.py"_matlab.html; Create plots via "MatLab"_matlab numerical analysis program
"mdump.py"_mdump.html; Read, write, manipulate mesh dump files
"pair.py"_pair.html; Compute LAMMPS pairwise energies
"patch.py"_patch.html; Create patchy Lennard-Jones particles for LAMMPS input
"pdbfile.py"_pdbfile.html; Read, write PDB files in combo with LAMMPS snapshots
"plotview.py"_plotview.html; Plot multiple vectors from a data set
"rasmol.py"_rasmol.html; 3d visualization via "RasMol"_rasmol program
"raster.py"_raster.html; 3d visualization via "Raster3d"_raster3d program
"svg.py"_svg.html; 3d visualization via "SVG"_svg files
"tdump.py"_tdump.html; Read LAMMPS dump files with triangle info
"vcr.py"_vcr.html; VCR-style GUI for 3d interactive OpenGL visualization
"vec.py"_vec.html; Create numeric vectors from columns in file or list of vecs
"vtk.py"_vtk.html; Convert LAMMPS snapshots to VTK format
"vmd.py"_vmd.html; Wrapper on "VMD visualization package"_vmd
"xyz.py"_xyz.html; Convert LAMMPS snapshots to XYZ format :tb(s=;)
:link(gnuplot,http://www.gnuplot.info)
:link(matlab,http://www.mathworks.com)
:link(rasmol,http://www.openrasmol.org)
:link(raster3d,http://www.bmsc.washington.edu/raster3d/raster3d.html)
:link(svg,http://www.w3.org/Graphics/SVG)
:link(ensight,http://www.ensight.com)
:link(ccell,http://www.cs.sandia.gov/~sjplimp/cell.html)
:link(vmd,http://www.ks.uiuc.edu/Research/vmd)
This diagram represents the different ways tools can be interconnected
by Pizza.py. Tools within the same red box are tools that are
(roughly) interchangeable.
:c,image(tools.jpg)

61
doc/animate.html Normal file
View File

@ -0,0 +1,61 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>animate tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Animate a series of image files.
</P>
<P><B>Description:</B>
</P>
<P>The animate tool displays a GUI to view and animate a series of image
files.
</P>
<P>The animate constructor creates the GUI. The animation can be
controlled by the GUI widgets or by invoking the tool methods: play(),
stop(), next(), etc. The frame slider can be dragged to view a
desired frame.
</P>
<P>Image files can be in any format (PNG, GIF, BMP, etc) recognized by
the Python Image Library (PIL) installed in your Python. Various
Pizza.py visualization tools (raster, rasmol, etc) create such image
files. If a particular image format fails to load, your PIL
installation was linked without support for that format. Rebuild PIL,
and follow its install instructions.
</P>
<P><B>Usage:</B>
</P>
<PRE>a = animate("image*.png") create GUI to animate set of image files
</PRE>
<PRE>Actions (same as GUI widgets):
</PRE>
<PRE>a.first() go to first frame
a.prev() go to previous frame
a.back() play backwards from current frame to start
a.stop() stop on current frame
a.play() play from current frame to end
a.next() go to next frame
a.last() go to last frame
</PRE>
<PRE>a.frame(31) set frame slider
a.delay(0.4) set delay slider
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "gl.html">gl</A>, <A HREF = "raster.html">raster</A>, <A HREF = "rasmol.html">rasmol</A>,
<A HREF = "svg.html">svg</A>, <A HREF = "vcr.html">vcr</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Python Tkinter and PIL packages.
</P>
</HTML>

56
doc/animate.txt Normal file
View File

@ -0,0 +1,56 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
animate tool :h3
[Purpose:]
Animate a series of image files.
[Description:]
The animate tool displays a GUI to view and animate a series of image
files.
The animate constructor creates the GUI. The animation can be
controlled by the GUI widgets or by invoking the tool methods: play(),
stop(), next(), etc. The frame slider can be dragged to view a
desired frame.
Image files can be in any format (PNG, GIF, BMP, etc) recognized by
the Python Image Library (PIL) installed in your Python. Various
Pizza.py visualization tools (raster, rasmol, etc) create such image
files. If a particular image format fails to load, your PIL
installation was linked without support for that format. Rebuild PIL,
and follow its install instructions.
[Usage:]
a = animate("image*.png") create GUI to animate set of image files :pre
Actions (same as GUI widgets): :pre
a.first() go to first frame
a.prev() go to previous frame
a.back() play backwards from current frame to start
a.stop() stop on current frame
a.play() play from current frame to end
a.next() go to next frame
a.last() go to last frame :pre
a.frame(31) set frame slider
a.delay(0.4) set delay slider :pre
[Related tools:]
"gl"_gl.html, "raster"_raster.html, "rasmol"_rasmol.html,
"svg"_svg.html, "vcr"_vcr.html
[Prerequisites:]
Python Tkinter and PIL packages.

109
doc/bdump.html Normal file
View File

@ -0,0 +1,109 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>bdump tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read dump files with bond info.
</P>
<P><B>Description:</B>
</P>
<P>The bdump tool reads one or more LAMMPS dump files, and stores their
contents as a series of snapshots with 2d arrays of atom attributes.
It is assumed that each entry contains info for a bond in a LAMMPS
simulation as is typically written by the dump local command in
LAMMPS. Other tools use bdump objects to extract bond info for
visualization, like the dump tool via its extra() method.
</P>
<P>The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
</P>
<P>The map() method assigns names to columns of attributes. The
id,type,atom1,atom2 names must be assigned in order for bond info to
be extracted.
</P>
<P>The viz() method is called by Pizza.py tools that visualize snapshots
of atoms (e.g. gl, raster, svg tools).
</P>
<HR>
<P>Normally, <A HREF = "http://lammps.sandia.gov">LAMMPS</A> creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump local files is simple. Each snapshot is formatted as
follows:
</P>
<PRE>ITEM: TIMESTEP
100
ITEM: NUMBER OF ENTRIES
32
ITEM: ENTRIES
1 1 5 10
2 1 11 45
3 2 6 8
...
N -3 23 456
</PRE>
<P>There are N lines following "ITEM: ENTRIES" where N is the number of
entries. Entries do not have to be listed in any particular order.
There can be a different number of entries in each snapshot. Each
line must contain the bond ID, type, and the 2 atom IDs of the atoms
in the bond, as specified by the map() command.
</P>
<HR>
<P><B>Usage:</B>
</P>
<PRE>b = bdump("dump.one") read in one or more dump files
b = bdump("dump.1 dump.2.gz") can be gzipped
b = bdump("dump.*") wildcard expands to multiple files
b = bdump("dump.*",0) two args = store filenames, but don't read
</PRE>
<PRE> incomplete and duplicate snapshots are deleted
no column name assignment is performed
</PRE>
<PRE>time = b.next() read next snapshot from dump files
</PRE>
<PRE> used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment is performed
</PRE>
<PRE>b.map(1,"id",3,"x") assign names to atom columns (1-N)
</PRE>
<PRE> must assign id,type,atom1,atom2
</PRE>
<PRE>time,box,atoms,bonds,tris,lines = b.viz(index) return list of viz objects
</PRE>
<PRE> viz() returns line info for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = NULL
atoms = NULL
bonds = id,type,atom1,atom2 for each line as 2d array
tris = NULL
lines = NULL
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "gl.html">gl</A>, <A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).
</P>
</HTML>

104
doc/bdump.txt Normal file
View File

@ -0,0 +1,104 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
bdump tool :h3
[Purpose:]
Read dump files with bond info.
[Description:]
The bdump tool reads one or more LAMMPS dump files, and stores their
contents as a series of snapshots with 2d arrays of atom attributes.
It is assumed that each entry contains info for a bond in a LAMMPS
simulation as is typically written by the dump local command in
LAMMPS. Other tools use bdump objects to extract bond info for
visualization, like the dump tool via its extra() method.
The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
The map() method assigns names to columns of attributes. The
id,type,atom1,atom2 names must be assigned in order for bond info to
be extracted.
The viz() method is called by Pizza.py tools that visualize snapshots
of atoms (e.g. gl, raster, svg tools).
:line
Normally, "LAMMPS"_http://lammps.sandia.gov creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump local files is simple. Each snapshot is formatted as
follows:
ITEM: TIMESTEP
100
ITEM: NUMBER OF ENTRIES
32
ITEM: ENTRIES
1 1 5 10
2 1 11 45
3 2 6 8
...
N -3 23 456 :pre
There are N lines following "ITEM: ENTRIES" where N is the number of
entries. Entries do not have to be listed in any particular order.
There can be a different number of entries in each snapshot. Each
line must contain the bond ID, type, and the 2 atom IDs of the atoms
in the bond, as specified by the map() command.
:line
[Usage:]
b = bdump("dump.one") read in one or more dump files
b = bdump("dump.1 dump.2.gz") can be gzipped
b = bdump("dump.*") wildcard expands to multiple files
b = bdump("dump.*",0) two args = store filenames, but don't read :pre
incomplete and duplicate snapshots are deleted
no column name assignment is performed :pre
time = b.next() read next snapshot from dump files :pre
used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment is performed :pre
b.map(1,"id",3,"x") assign names to atom columns (1-N) :pre
must assign id,type,atom1,atom2 :pre
time,box,atoms,bonds,tris,lines = b.viz(index) return list of viz objects :pre
viz() returns line info for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = NULL
atoms = NULL
bonds = id,type,atom1,atom2 for each line as 2d array
tris = NULL
lines = NULL :pre
[Related tools:]
"dump"_dump.html, "gl"_gl.html, "raster"_raster.html, "svg"_svg.html
[Prerequisites:]
Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).

224
doc/cdata.html Normal file
View File

@ -0,0 +1,224 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>cdata tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read, create, manipulate ChemCell data files.
</P>
<P><B>Description:</B>
</P>
<P>The cdata tool reads and writes ChemCell data files which contain
particle and surface information. It enables the creation of
geometric models of cells for input to ChemCell.
</P>
<P>The cdata constructor reads in the specified LAMMPS data file. With
no argument, an empty cdata object is created which can have objects
added to it later, and then be written out.
</P>
<P>A cdata object or file contains "objects" of different types. Each
object has a unique user-assigned ID. Objects can be of several
types: "group", "triangles", "region", "facets", or "lines". A group
is a list of particles, all of the same type. Triangles define a
surface and include a list of vertices, triangle definitions, and
adjacent edge connections. A region is a geometric object that
defines a surface, such as a sphere. Facets are a CUBIT meshing
format that defines a set of vertices and triangles; it is converted
into a triangles entry. Lines are a collection of line segments.
</P>
<P>The box(), sphere(), shell(), cyl(), and cap() methods create a new
"region" object. The q() method sets triangulations factors that are
used when the region is converted into a triangulated surface for
output or visualization.
</P>
<P>The line() and ibox() methods create a "lines" object.
</P>
<P>The surf() method creates a "triangles" object from a region, using
the q() parameters. The surftri() method creats a new "triangles"
object from a list of triangle indices belonging to another surface.
The surfselect() method applies an if test to vertices and triangles
in another surface to choose a subset of them to form a new
"triangles" object. The bins() method sets the number of bins in x,y
when surfaces are binned for the purpose of creating particles
inside/outside the surface.
</P>
<P>The part(), part2d(), partarray(), and partring() methods create a
"group" of particles inside, outside, or on regions or triangulated
surfaces. Particles are 3d by default, or 2d if created on a surface.
The partsurf() method can be used to change the name of the surface 2d
particles are on, since that attribute is written to a file when the
particles are output. The creation of particles uses a random #
generator whose initial seed can be set via the seed() method.
</P>
<P>The random() method can be used to pick a random point on the surface
of a "region" or "triangles" object. The project() method maps
particles to the surface of a "region" or "triangulate" object.
</P>
<P>The center(), trans(), rotate(), and scale() methods are used to
perform a geometric transformation on a "group" of particles or a
"triangles" object. The union() method creates a new object of
"union" type from a list of objects. The join() method does the same
thing except all objects in the list must be of the same type and the
new object is also of that type. A join() can only be done for
"group", "triangles", or "line" objects. The delete(), rename(), and
copy() methods manipulate the IDs of previously defined objects.
</P>
<P>Be default all objects are selected when created. The select() and
unselect() methods can be used to select a subset of existing objects.
The write() and append() methods write out selected objects to a file.
</P>
<P>The iterator() and viz() methods are called by Pizza.py tools that
visualize snapshots of atoms (e.g. gl, raster, svg tools). Only
selected objects are returned to the caller. A cdata file can be
visualzed similarly to a snapshots from a dump file. In the case of a
cdata file, there is only a single snapshot with index 0.
</P>
<P><B>Usage:</B>
</P>
<PRE>c = cdata() create a datafile object
c = cdata("mem.surf") read in one or more ChemCell data files
c = cdata("mem.part.gz mem.surf") can be gzipped
c = cdata("mem.*") wildcard expands to multiple files
c.read("mem.surf") read in one or more data files
</PRE>
<PRE> read() has same argument options as constructor
files contain the following kinds of entries, each of which becomes an object
particles, triangles, region, facets
particles is a list of particles -> becomes a group
triangles is 3 lists of vertices, triangles, connections -> becomes a surf
region is a ChemCell command defining a region -> becomes a region
facets is a CUBIT format of vertices and triangles -> becomes a surf
each object is assigned an ID = name in file
ID can be any number or string, must be unique
</PRE>
<PRE>c.box(ID,xlo,ylo,zlo,xhi,yhi,zhi) create a box region
c.sphere(ID,x,y,z,r) create a sphere region
c.shell(ID,x,y,z,r,rinner) create a shell region
c.cyl(ID,'x',c1,c2,r,lo,hi) create a axis-aligned cylinder region
c.cap(ID,'x',c1,c2,r,lo,hi) create a axis-aligned capped-cylinder region
c.q(ID,q1,q2,...) set region triangulation quality factors
</PRE>
<PRE> box() can create an axis-aligned plane, line, or point if lo=hi
cyl() can create an axis-aligned circle if lo=hi
for cyl() and cap(): 'x' c1,c2 = y,z; 'y' c1,c2 = x,z; 'z' c,c2 = x,y
q's are size factors for region triangulation
for box, q1,q2,q3 = # of divisions per xyz of box
for sphere or shell, q1 = # of divisions per face edge of embedded cube
for cyl or cap, q1 = # of divisions per face edge of end cap, must be even
q2 = # of divisions along length of cylinder
</PRE>
<PRE>c.line(ID,x1,y1,z1,x2,y2,z2) create a line object with one line
c.lbox(ID,xlo,ylo,zlo,xhi,yhi,zhi) create a line object with 12 box lines
</PRE>
<PRE>c.surf(ID,id-region) create a triangulated surf from a region
c.surftri(ID,id-surf,t1,t2,...) create a tri surf from list of id-surf tris
c.surfselect(ID,id-surf,test) create a tri surf from test on id-surf tris
c.bins(ID,nx,ny) set binning parameters for a surf
</PRE>
<PRE> triangulation of a shell is just done for the outer sphere
for surftri(), one or more tri indices (1-N) must be listed
for surfselect(), test is string like "$x < 2.0 and $y > 0.0"
bins are used when particles are created inside/outside a surf
</PRE>
<PRE>c.part(ID,n,id_in) create N particles inside object id_in
c.part(ID,n,id_in,id_out) particles are also outside object id_out
c.part2d(ID,n,id_on) create 2d particles on object id_on
c.partarray(ID,nx,nz,nz,x,y,z,dx,dy,dz) create 3d grid of particles
c.partring(ID,n,x,y,z,r,'x') create ring of particles
c.partsurf(ID,id_on) change surf of existing 2d particle group
c.seed(43284) set random # seed (def = 12345)
</PRE>
<PRE> generate particle positions randomly (unless otherwise noted)
for part(), id_in and id_out must be IDs of a surf, region, or union object
inside a union object means inside any of the lower-level objects
outside a union object means outside all of the lower-level objects
for part2d(), id_on must be ID of a surf, region, or union object
for part2d(), particles will be written as 2d assigned to surf id_on
for partring(), ring axis is in 'x','y', or 'z' direction
partsurf() changes surf id_on for an existing 2d particle group
</PRE>
<PRE>x,n = c.random(ID) pick a random pt on surf of object ID
c.project(ID,ID2,dx,dy,dz,eps,fg) project particles in ID to surf of obj ID2
</PRE>
<PRE> random() returns pt = [x,y,z] and normal vec n [nx,ny,nz]
for random(), ID can be surf or region obj
project() remaps particle coords in group ID
moves each particle along dir until they are within eps of surface
if no fg arg, dir = (dx,dy,dz)
if fg arg, dir = line from particle coord to (dx,dy,dz)
ID2 can be surf or region obj
particles are converted to 2d assigned to surf ID2
</PRE>
<PRE>c.center(ID,x,y,z) set center point of object
c.trans(ID,dx,dy,dz) translate an object
c.rotate(ID,'x',1,1,0,'z',-1,1,0) rotate an object
c.scale(ID,sx,sy,sz) scale an object
</PRE>
<PRE> objects must be surface or particle group, regions cannot be changed
for center(), default is middle of bounding box (set when obj is created)
for rotate(), set any 2 axes, must be orthogonal, 3rd is inferred
object is rotated so that it's current xyz axes point along new ones
rotation and scaling occur relative to center point
</PRE>
<PRE>c.union(ID,id1,id2,...) create a new union object from id1,id2,etc
c.join(ID,id1,id2,...) create a new object by joining id1,id2,etc
c.delete(id1,id2,...) delete one or more objects
c.rename(ID,IDnew) rename an object
c.copy(ID,IDnew) create a new object as copy of old object
</PRE>
<PRE> for union, all lower-level objects must be of surface, region, or union style
for join, all joined objects must be of same style: group, surf, line
new object is the same style
</PRE>
<PRE>c.select(id1,id2,...) select one or more objects
c.select() select all objects
c.unselect(id1,id2,...) unselect one or more objects
c.unselect() unselect all objects
</PRE>
<PRE> selection applies to write() and viz()
</PRE>
<PRE>c.write("file") write all selected objs to ChemCell file
c.write("file",id1,id2,...) write only listed & selected objects to file
c.append("file") append all selected objs to ChemCell file
c.append("file",id1,id2,...) append only listed & selected objects
</PRE>
<PRE> union objects are skipped, not written to file
</PRE>
<PRE>index,time,flag = c.iterator(0/1) loop over single snapshot
time,box,atoms,bonds,tris,lines = c.viz(index) return list of viz objects
</PRE>
<PRE> iterator() and viz() are compatible with equivalent dump calls
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = timestep index within dump object (only 0 for data file)
time = timestep value (only 0 for data file)
flag = -1 when iteration is done, 1 otherwise
viz() returns info for selected objs for specified timestep index (must be 0)
time = 0
box = [xlo,ylo,zlo,xhi,yhi,zhi]
atoms = id,type,x,y,z for each atom as 2d array
NULL if atoms do not exist
bonds = NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
regions are triangulated according to q() settings by viz()
NULL if surfaces do not exist
lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
NULL if lines do not exist
types are assigned to each object of same style in ascending order
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "clog.html">clog</A>, <A HREF = "data.html">data</A>, <A HREF = "gl.html">gl</A>,
<A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

219
doc/cdata.txt Normal file
View File

@ -0,0 +1,219 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
cdata tool :h3
[Purpose:]
Read, create, manipulate ChemCell data files.
[Description:]
The cdata tool reads and writes ChemCell data files which contain
particle and surface information. It enables the creation of
geometric models of cells for input to ChemCell.
The cdata constructor reads in the specified LAMMPS data file. With
no argument, an empty cdata object is created which can have objects
added to it later, and then be written out.
A cdata object or file contains "objects" of different types. Each
object has a unique user-assigned ID. Objects can be of several
types: "group", "triangles", "region", "facets", or "lines". A group
is a list of particles, all of the same type. Triangles define a
surface and include a list of vertices, triangle definitions, and
adjacent edge connections. A region is a geometric object that
defines a surface, such as a sphere. Facets are a CUBIT meshing
format that defines a set of vertices and triangles; it is converted
into a triangles entry. Lines are a collection of line segments.
The box(), sphere(), shell(), cyl(), and cap() methods create a new
"region" object. The q() method sets triangulations factors that are
used when the region is converted into a triangulated surface for
output or visualization.
The line() and ibox() methods create a "lines" object.
The surf() method creates a "triangles" object from a region, using
the q() parameters. The surftri() method creats a new "triangles"
object from a list of triangle indices belonging to another surface.
The surfselect() method applies an if test to vertices and triangles
in another surface to choose a subset of them to form a new
"triangles" object. The bins() method sets the number of bins in x,y
when surfaces are binned for the purpose of creating particles
inside/outside the surface.
The part(), part2d(), partarray(), and partring() methods create a
"group" of particles inside, outside, or on regions or triangulated
surfaces. Particles are 3d by default, or 2d if created on a surface.
The partsurf() method can be used to change the name of the surface 2d
particles are on, since that attribute is written to a file when the
particles are output. The creation of particles uses a random #
generator whose initial seed can be set via the seed() method.
The random() method can be used to pick a random point on the surface
of a "region" or "triangles" object. The project() method maps
particles to the surface of a "region" or "triangulate" object.
The center(), trans(), rotate(), and scale() methods are used to
perform a geometric transformation on a "group" of particles or a
"triangles" object. The union() method creates a new object of
"union" type from a list of objects. The join() method does the same
thing except all objects in the list must be of the same type and the
new object is also of that type. A join() can only be done for
"group", "triangles", or "line" objects. The delete(), rename(), and
copy() methods manipulate the IDs of previously defined objects.
Be default all objects are selected when created. The select() and
unselect() methods can be used to select a subset of existing objects.
The write() and append() methods write out selected objects to a file.
The iterator() and viz() methods are called by Pizza.py tools that
visualize snapshots of atoms (e.g. gl, raster, svg tools). Only
selected objects are returned to the caller. A cdata file can be
visualzed similarly to a snapshots from a dump file. In the case of a
cdata file, there is only a single snapshot with index 0.
[Usage:]
c = cdata() create a datafile object
c = cdata("mem.surf") read in one or more ChemCell data files
c = cdata("mem.part.gz mem.surf") can be gzipped
c = cdata("mem.*") wildcard expands to multiple files
c.read("mem.surf") read in one or more data files :pre
read() has same argument options as constructor
files contain the following kinds of entries, each of which becomes an object
particles, triangles, region, facets
particles is a list of particles -> becomes a group
triangles is 3 lists of vertices, triangles, connections -> becomes a surf
region is a ChemCell command defining a region -> becomes a region
facets is a CUBIT format of vertices and triangles -> becomes a surf
each object is assigned an ID = name in file
ID can be any number or string, must be unique :pre
c.box(ID,xlo,ylo,zlo,xhi,yhi,zhi) create a box region
c.sphere(ID,x,y,z,r) create a sphere region
c.shell(ID,x,y,z,r,rinner) create a shell region
c.cyl(ID,'x',c1,c2,r,lo,hi) create a axis-aligned cylinder region
c.cap(ID,'x',c1,c2,r,lo,hi) create a axis-aligned capped-cylinder region
c.q(ID,q1,q2,...) set region triangulation quality factors :pre
box() can create an axis-aligned plane, line, or point if lo=hi
cyl() can create an axis-aligned circle if lo=hi
for cyl() and cap(): 'x' c1,c2 = y,z; 'y' c1,c2 = x,z; 'z' c,c2 = x,y
q's are size factors for region triangulation
for box, q1,q2,q3 = # of divisions per xyz of box
for sphere or shell, q1 = # of divisions per face edge of embedded cube
for cyl or cap, q1 = # of divisions per face edge of end cap, must be even
q2 = # of divisions along length of cylinder :pre
c.line(ID,x1,y1,z1,x2,y2,z2) create a line object with one line
c.lbox(ID,xlo,ylo,zlo,xhi,yhi,zhi) create a line object with 12 box lines :pre
c.surf(ID,id-region) create a triangulated surf from a region
c.surftri(ID,id-surf,t1,t2,...) create a tri surf from list of id-surf tris
c.surfselect(ID,id-surf,test) create a tri surf from test on id-surf tris
c.bins(ID,nx,ny) set binning parameters for a surf :pre
triangulation of a shell is just done for the outer sphere
for surftri(), one or more tri indices (1-N) must be listed
for surfselect(), test is string like "$x < 2.0 and $y > 0.0"
bins are used when particles are created inside/outside a surf :pre
c.part(ID,n,id_in) create N particles inside object id_in
c.part(ID,n,id_in,id_out) particles are also outside object id_out
c.part2d(ID,n,id_on) create 2d particles on object id_on
c.partarray(ID,nx,nz,nz,x,y,z,dx,dy,dz) create 3d grid of particles
c.partring(ID,n,x,y,z,r,'x') create ring of particles
c.partsurf(ID,id_on) change surf of existing 2d particle group
c.seed(43284) set random # seed (def = 12345) :pre
generate particle positions randomly (unless otherwise noted)
for part(), id_in and id_out must be IDs of a surf, region, or union object
inside a union object means inside any of the lower-level objects
outside a union object means outside all of the lower-level objects
for part2d(), id_on must be ID of a surf, region, or union object
for part2d(), particles will be written as 2d assigned to surf id_on
for partring(), ring axis is in 'x','y', or 'z' direction
partsurf() changes surf id_on for an existing 2d particle group :pre
x,n = c.random(ID) pick a random pt on surf of object ID
c.project(ID,ID2,dx,dy,dz,eps,fg) project particles in ID to surf of obj ID2 :pre
random() returns pt = \[x,y,z\] and normal vec n \[nx,ny,nz\]
for random(), ID can be surf or region obj
project() remaps particle coords in group ID
moves each particle along dir until they are within eps of surface
if no fg arg, dir = (dx,dy,dz)
if fg arg, dir = line from particle coord to (dx,dy,dz)
ID2 can be surf or region obj
particles are converted to 2d assigned to surf ID2 :pre
c.center(ID,x,y,z) set center point of object
c.trans(ID,dx,dy,dz) translate an object
c.rotate(ID,'x',1,1,0,'z',-1,1,0) rotate an object
c.scale(ID,sx,sy,sz) scale an object :pre
objects must be surface or particle group, regions cannot be changed
for center(), default is middle of bounding box (set when obj is created)
for rotate(), set any 2 axes, must be orthogonal, 3rd is inferred
object is rotated so that it's current xyz axes point along new ones
rotation and scaling occur relative to center point :pre
c.union(ID,id1,id2,...) create a new union object from id1,id2,etc
c.join(ID,id1,id2,...) create a new object by joining id1,id2,etc
c.delete(id1,id2,...) delete one or more objects
c.rename(ID,IDnew) rename an object
c.copy(ID,IDnew) create a new object as copy of old object :pre
for union, all lower-level objects must be of surface, region, or union style
for join, all joined objects must be of same style: group, surf, line
new object is the same style :pre
c.select(id1,id2,...) select one or more objects
c.select() select all objects
c.unselect(id1,id2,...) unselect one or more objects
c.unselect() unselect all objects :pre
selection applies to write() and viz() :pre
c.write("file") write all selected objs to ChemCell file
c.write("file",id1,id2,...) write only listed & selected objects to file
c.append("file") append all selected objs to ChemCell file
c.append("file",id1,id2,...) append only listed & selected objects :pre
union objects are skipped, not written to file :pre
index,time,flag = c.iterator(0/1) loop over single snapshot
time,box,atoms,bonds,tris,lines = c.viz(index) return list of viz objects :pre
iterator() and viz() are compatible with equivalent dump calls
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = timestep index within dump object (only 0 for data file)
time = timestep value (only 0 for data file)
flag = -1 when iteration is done, 1 otherwise
viz() returns info for selected objs for specified timestep index (must be 0)
time = 0
box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
atoms = id,type,x,y,z for each atom as 2d array
NULL if atoms do not exist
bonds = NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
regions are triangulated according to q() settings by viz()
NULL if surfaces do not exist
lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
NULL if lines do not exist
types are assigned to each object of same style in ascending order :pre
[Related tools:]
"clog"_clog.html, "data"_data.html, "gl"_gl.html,
"raster"_raster.html, "svg"_svg.html
[Prerequisites:] none

60
doc/cfg.html Normal file
View File

@ -0,0 +1,60 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>cfg tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Convert LAMMPS snapshots to AtomEye CFG format.
</P>
<P><B>Description:</B>
</P>
<P>The cfg tool converts atom snapshots in a LAMMPS dump or data file to
the CFG format used by the <A HREF = "http://164.107.79.177/Archive/Graphics/A">AtomEye</A> visualization tool.
</P>
<P>The cfg constructor takes an object that stores atom snapshots
(<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>) as its first argument. The atom
snapshots must have "id", "type", "x", "y", and "z" defined; see the
map() methods of those tools.
</P>
<P>The one(), many(), and single() methods convert specific snapshots to
the CFG format and write them out. Optionally, a file prefix for the
CFG output files can also be specified. A ".cfg" suffix will be
appended to all output files.
</P>
<P>If your atom snapshots are not sorted by atom ID (e.g. because they
were written out by a parallel LAMMPS run), then you may want to sort
them before converting them to CFG files with this tool. This can be
done by "d = dump("tmp.dump"); d.sort()". This is because AtomEye
does not use atom IDs directly but infers an ID by the order of atoms
as they appear in the CFG file.
</P>
<P><B>Usage:</B>
</P>
<PRE>c = cfg(d) d = object containing atom coords (dump, data)
</PRE>
<PRE>c.one() write all snapshots to tmp.cfg
c.one("new") write all snapshots to new.cfg
c.many() write snapshots to tmp0000.cfg, tmp0001.cfg, etc
c.many("new") write snapshots to new0000.cfg, new0001.cfg, etc
c.single(N) write snapshot for timestep N to tmp.cfg
c.single(N,"file") write snapshot for timestep N to file.cfg
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "data.html">data</A>, <A HREF = "dump.html">dump</A>, <A HREF = "ensight.html">ensight</A>,
<A HREF = "vtk.html">vtk</A>, <A HREF = "xyz.html">xyz</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

55
doc/cfg.txt Normal file
View File

@ -0,0 +1,55 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
cfg tool :h3
[Purpose:]
Convert LAMMPS snapshots to AtomEye CFG format.
[Description:]
The cfg tool converts atom snapshots in a LAMMPS dump or data file to
the CFG format used by the "AtomEye"_atomeye visualization tool.
:link(atomeye,http://164.107.79.177/Archive/Graphics/A)
The cfg constructor takes an object that stores atom snapshots
("dump"_dump.html, "data"_data.html) as its first argument. The atom
snapshots must have "id", "type", "x", "y", and "z" defined; see the
map() methods of those tools.
The one(), many(), and single() methods convert specific snapshots to
the CFG format and write them out. Optionally, a file prefix for the
CFG output files can also be specified. A ".cfg" suffix will be
appended to all output files.
If your atom snapshots are not sorted by atom ID (e.g. because they
were written out by a parallel LAMMPS run), then you may want to sort
them before converting them to CFG files with this tool. This can be
done by "d = dump("tmp.dump"); d.sort()". This is because AtomEye
does not use atom IDs directly but infers an ID by the order of atoms
as they appear in the CFG file.
[Usage:]
c = cfg(d) d = object containing atom coords (dump, data) :pre
c.one() write all snapshots to tmp.cfg
c.one("new") write all snapshots to new.cfg
c.many() write snapshots to tmp0000.cfg, tmp0001.cfg, etc
c.many("new") write snapshots to new0000.cfg, new0001.cfg, etc
c.single(N) write snapshot for timestep N to tmp.cfg
c.single(N,"file") write snapshot for timestep N to file.cfg :pre
[Related tools:]
"data"_data.html, "dump"_dump.html, "ensight"_ensight.html,
"vtk"_vtk.html, "xyz"_xyz.html
[Prerequisites:] none

72
doc/chain.html Normal file
View File

@ -0,0 +1,72 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>chain tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Create bead-spring chains for LAMMPS input.
</P>
<P><B>Description:</B>
</P>
<P>The chain tool creates random, overlapping bead-spring (FENE) chains
and writes them out as a LAMMPS data file. They need to be simulated
with a soft potential in LAMMPS to un-overlap them before they form
a proper melt.
</P>
<P>The chain constructor uses the total number of monomers and the
Lennard-Jones reduced density to create a simulation box of the
appropriate size. Optionally, the box shape can also be specified.
</P>
<P>The build() method creates N chains, each with M monomers. It can be
invoked multiple times to create sets of chains with different
properties. The starting point of each chain is chosen randomly, as
is the position of subsequent monomers. The seed value sets the
random number generator used for coordinate generation.
</P>
<P>The mtype, btype, blen, and dmin settings affect how the chain and its
monomers are created. Dmin is the minimum distance allowed between a
new monomer and the monomer two before it, so it determines the
stiffness of the chain. Each monomer is assigned a molecule ID as it
is created, in accord with the id setting.
</P>
<P>Once N total monomers have been created, the ensemble of chains is
written to a LAMMPS data file via the write() method.
</P>
<P><B>Usage:</B>
</P>
<PRE>c = chain(N,rho) setup box with N monomers at reduced density rho
c = chain(N,rho,1,1,2) x,y,z = aspect ratio of box (def = 1,1,1)
</PRE>
<PRE>c.seed = 48379 set random # seed (def = 12345)
c.mtype = 2 set type of monomers (def = 1)
c.btype = 1 set type of bonds (def = 1)
c.blen = 0.97 set length of bonds (def = 0.97)
c.dmin = 1.02 set min dist from i-1 to i+1 site (def = 1.02)
</PRE>
<PRE>c.id = "chain" set molecule ID to chain # (default)
c.id = "end1" set molecule ID to count from one end of chain
c.id = "end2" set molecule ID to count from either end of chain
</PRE>
<PRE>c.build(100,10) create 100 chains, each of length 10
</PRE>
<PRE> can be invoked multiple times interleaved with different settings
must fill box with total of N monomers
</PRE>
<PRE>c.write("data.file") write out all built chains to LAMMPS data file
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "data.html">data</A>, <A HREF = "patch.html">patch</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

67
doc/chain.txt Normal file
View File

@ -0,0 +1,67 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
chain tool :h3
[Purpose:]
Create bead-spring chains for LAMMPS input.
[Description:]
The chain tool creates random, overlapping bead-spring (FENE) chains
and writes them out as a LAMMPS data file. They need to be simulated
with a soft potential in LAMMPS to un-overlap them before they form
a proper melt.
The chain constructor uses the total number of monomers and the
Lennard-Jones reduced density to create a simulation box of the
appropriate size. Optionally, the box shape can also be specified.
The build() method creates N chains, each with M monomers. It can be
invoked multiple times to create sets of chains with different
properties. The starting point of each chain is chosen randomly, as
is the position of subsequent monomers. The seed value sets the
random number generator used for coordinate generation.
The mtype, btype, blen, and dmin settings affect how the chain and its
monomers are created. Dmin is the minimum distance allowed between a
new monomer and the monomer two before it, so it determines the
stiffness of the chain. Each monomer is assigned a molecule ID as it
is created, in accord with the id setting.
Once N total monomers have been created, the ensemble of chains is
written to a LAMMPS data file via the write() method.
[Usage:]
c = chain(N,rho) setup box with N monomers at reduced density rho
c = chain(N,rho,1,1,2) x,y,z = aspect ratio of box (def = 1,1,1) :pre
c.seed = 48379 set random # seed (def = 12345)
c.mtype = 2 set type of monomers (def = 1)
c.btype = 1 set type of bonds (def = 1)
c.blen = 0.97 set length of bonds (def = 0.97)
c.dmin = 1.02 set min dist from i-1 to i+1 site (def = 1.02) :pre
c.id = "chain" set molecule ID to chain # (default)
c.id = "end1" set molecule ID to count from one end of chain
c.id = "end2" set molecule ID to count from either end of chain :pre
c.build(100,10) create 100 chains, each of length 10 :pre
can be invoked multiple times interleaved with different settings
must fill box with total of N monomers :pre
c.write("data.file") write out all built chains to LAMMPS data file :pre
[Related tools:]
"data"_data.html, "patch"_patch.html
[Prerequisites:] none

62
doc/clog.html Normal file
View File

@ -0,0 +1,62 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>clog tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read ChemCell and SPPARKS log files and extract time-series data.
</P>
<P><B>Description:</B>
</P>
<P>Read one or more ChemCell log files and combine their species
statistical data into long, named vectors (versus time). The vectors
can be used in Python for further processing and plotting, or they can
be output to a file.
</P>
<P>The log constructor reads one or more log files. If 2 arguments are
specified, a single file is specified, and it is assumed to contain
data for multiple runs, which are averaged.
</P>
<P>The nvec, nlen, and names values give the # of vectors, their length,
and names. The get() method returns one of more vectors as a Python
list. The write() method outputs the numeric vectors to a file.
</P>
<P><B>Usage:</B>
</P>
<PRE>c = clog("file1") read in one or more log files
c = clog("log1 log2.gz") can be gzipped
c = clog("file*") wildcard expands to multiple files
c = clog("log.cell","Time") 2nd arg = start string for time section
c = clog("log.cell","",0) 3rd arg = average all runs
</PRE>
<PRE> incomplete and duplicate thermo entries are deleted
if specify 2nd arg, it delimits a time section
no 2nd arg or empty string, use default which is ChemCell specific
if specify any 3rd arg, average all runs, assume all start at time 0
</PRE>
<PRE>nvec = c.nvec # of vectors of thermo info
nlen = c.nlen length of each vectors
names = c.names list of vector names
a,b,... = c.get("A","B",...) return one or more vectors of values
c.write("file.txt") write all vectors to a file
c.write("file.txt","A","B",...) write listed vectors to a file
</PRE>
<PRE> get and write allow abbreviated (uniquely) vector names
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "plotview.html">plotview</A>, <A HREF = "gnu.html">gnu</A>, <A HREF = "log.html">log</A>,
<A HREF = "matlab.html">matlab</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

57
doc/clog.txt Normal file
View File

@ -0,0 +1,57 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
clog tool :h3
[Purpose:]
Read ChemCell and SPPARKS log files and extract time-series data.
[Description:]
Read one or more ChemCell log files and combine their species
statistical data into long, named vectors (versus time). The vectors
can be used in Python for further processing and plotting, or they can
be output to a file.
The log constructor reads one or more log files. If 2 arguments are
specified, a single file is specified, and it is assumed to contain
data for multiple runs, which are averaged.
The nvec, nlen, and names values give the # of vectors, their length,
and names. The get() method returns one of more vectors as a Python
list. The write() method outputs the numeric vectors to a file.
[Usage:]
c = clog("file1") read in one or more log files
c = clog("log1 log2.gz") can be gzipped
c = clog("file*") wildcard expands to multiple files
c = clog("log.cell","Time") 2nd arg = start string for time section
c = clog("log.cell","",0) 3rd arg = average all runs :pre
incomplete and duplicate thermo entries are deleted
if specify 2nd arg, it delimits a time section
no 2nd arg or empty string, use default which is ChemCell specific
if specify any 3rd arg, average all runs, assume all start at time 0 :pre
nvec = c.nvec # of vectors of thermo info
nlen = c.nlen length of each vectors
names = c.names list of vector names
a,b,... = c.get("A","B",...) return one or more vectors of values
c.write("file.txt") write all vectors to a file
c.write("file.txt","A","B",...) write listed vectors to a file :pre
get and write allow abbreviated (uniquely) vector names :pre
[Related tools:]
"plotview"_plotview.html, "gnu"_gnu.html, "log"_log.html,
"matlab"_matlab.html
[Prerequisites:] none

107
doc/data.html Normal file
View File

@ -0,0 +1,107 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>data tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read, write, manipulate LAMMPS data files.
</P>
<P><B>Description:</B>
</P>
<P>The data tool reads and writes LAMMPS data files. It also allows
their content to be accessed or modified.
</P>
<P>The data constructor reads in the specified LAMMPS data file. With no
argument, an empty data object is created which can have fields added
to it later, and then be written out.
</P>
<P>The map() method assigns names to different atom attributes by their
column number (1-N). The get() method extracts columns of information
from the specified section of the data file.
</P>
<P>The title, headers, and sections variables can be set directly. The
header values correspond to one-line definition that appear at the top
of the data file. The box size values should be set to a Python
tuple, e.g.
</P>
<PRE>d.headers["xlo xhi"] = (-30, 30)
</PRE>
<P>The section value should be a list of text lines, each of which
includes a newline at the end.
</P>
<P>The delete() method deletes a header or entire section of the data
file. The replace() method allows one column of a section to be
replaced with a vector of new values. The newxyz() methods replaces
the xyz coords of the "Atoms" section of the data file with xyz values
from the Nth snapshot of a dump object containing snapshots.
</P>
<P>The iterator() and viz() methods are called by Pizza.py tools that
visualize snapshots of atoms (e.g. raster, svg tools). A data file
can be visualzed similarly to snapshots from a dump file. In the case
of a data file, there is only a single snapshot with index 0.
</P>
<P>The write() method outputs a LAMMPS data file.
</P>
<P><B>Usage:</B>
</P>
<PRE>d = data("data.poly") read a LAMMPS data file, can be gzipped
d = data() create an empty data file
</PRE>
<PRE>d.map(1,"id",3,"x") assign names to atom columns (1-N)
</PRE>
<PRE>coeffs = d.get("Pair Coeffs") extract info from data file section
q = d.get("Atoms",4)
</PRE>
<PRE> 1 arg = all columns returned as 2d array of floats
2 args = Nth column returned as vector of floats
</PRE>
<PRE>d.reorder("Atoms",1,3,2,4,5) reorder columns (1-N) in a data file section
</PRE>
<PRE> 1,3,2,4,5 = new order of previous columns, can delete columns this way
</PRE>
<PRE>d.title = "My LAMMPS data file" set title of the data file
d.headers["atoms"] = 1500 set a header value
d.sections["Bonds"] = lines set a section to list of lines (with newlines)
d.delete("bonds") delete a keyword or section of data file
d.delete("Bonds")
d.replace("Atoms",5,vec) replace Nth column of section with vector
d.newxyz(dmp,1000) replace xyz in Atoms with xyz of snapshot N
</PRE>
<PRE> newxyz assumes id,x,y,z are defined in both data and dump files
also replaces ix,iy,iz if they are defined
</PRE>
<PRE>index,time,flag = d.iterator(0/1) loop over single data file snapshot
time,box,atoms,bonds,tris,lines = d.viz(index) return list of viz objects
</PRE>
<PRE> iterator() and viz() are compatible with equivalent dump calls
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = timestep index within dump object (only 0 for data file)
time = timestep value (only 0 for data file)
flag = -1 when iteration is done, 1 otherwise
viz() returns info for specified timestep index (must be 0)
time = 0
box = [xlo,ylo,zlo,xhi,yhi,zhi]
atoms = id,type,x,y,z for each atom as 2d array
bonds = id,type,x1,y1,z1,x2,y2,z2,t1,t2 for each bond as 2d array
NULL if bonds do not exist
tris = NULL
lines = NULL
</PRE>
<PRE>d.write("data.new") write a LAMMPS data file
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "gl.html">gl</A>, <A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

102
doc/data.txt Normal file
View File

@ -0,0 +1,102 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
data tool :h3
[Purpose:]
Read, write, manipulate LAMMPS data files.
[Description:]
The data tool reads and writes LAMMPS data files. It also allows
their content to be accessed or modified.
The data constructor reads in the specified LAMMPS data file. With no
argument, an empty data object is created which can have fields added
to it later, and then be written out.
The map() method assigns names to different atom attributes by their
column number (1-N). The get() method extracts columns of information
from the specified section of the data file.
The title, headers, and sections variables can be set directly. The
header values correspond to one-line definition that appear at the top
of the data file. The box size values should be set to a Python
tuple, e.g.
d.headers\["xlo xhi"\] = (-30, 30) :pre
The section value should be a list of text lines, each of which
includes a newline at the end.
The delete() method deletes a header or entire section of the data
file. The replace() method allows one column of a section to be
replaced with a vector of new values. The newxyz() methods replaces
the xyz coords of the "Atoms" section of the data file with xyz values
from the Nth snapshot of a dump object containing snapshots.
The iterator() and viz() methods are called by Pizza.py tools that
visualize snapshots of atoms (e.g. raster, svg tools). A data file
can be visualzed similarly to snapshots from a dump file. In the case
of a data file, there is only a single snapshot with index 0.
The write() method outputs a LAMMPS data file.
[Usage:]
d = data("data.poly") read a LAMMPS data file, can be gzipped
d = data() create an empty data file :pre
d.map(1,"id",3,"x") assign names to atom columns (1-N) :pre
coeffs = d.get("Pair Coeffs") extract info from data file section
q = d.get("Atoms",4) :pre
1 arg = all columns returned as 2d array of floats
2 args = Nth column returned as vector of floats :pre
d.reorder("Atoms",1,3,2,4,5) reorder columns (1-N) in a data file section :pre
1,3,2,4,5 = new order of previous columns, can delete columns this way :pre
d.title = "My LAMMPS data file" set title of the data file
d.headers\["atoms"\] = 1500 set a header value
d.sections\["Bonds"\] = lines set a section to list of lines (with newlines)
d.delete("bonds") delete a keyword or section of data file
d.delete("Bonds")
d.replace("Atoms",5,vec) replace Nth column of section with vector
d.newxyz(dmp,1000) replace xyz in Atoms with xyz of snapshot N :pre
newxyz assumes id,x,y,z are defined in both data and dump files
also replaces ix,iy,iz if they are defined :pre
index,time,flag = d.iterator(0/1) loop over single data file snapshot
time,box,atoms,bonds,tris,lines = d.viz(index) return list of viz objects :pre
iterator() and viz() are compatible with equivalent dump calls
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = timestep index within dump object (only 0 for data file)
time = timestep value (only 0 for data file)
flag = -1 when iteration is done, 1 otherwise
viz() returns info for specified timestep index (must be 0)
time = 0
box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
atoms = id,type,x,y,z for each atom as 2d array
bonds = id,type,x1,y1,z1,x2,y2,z2,t1,t2 for each bond as 2d array
NULL if bonds do not exist
tris = NULL
lines = NULL :pre
d.write("data.new") write a LAMMPS data file :pre
[Related tools:]
"gl"_gl.html, "raster"_raster.html, "svg"_svg.html
[Prerequisites:] none

236
doc/dump.html Normal file
View File

@ -0,0 +1,236 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>dump tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read, write, manipulate dump files and particle attributes.
</P>
<P><B>Description:</B>
</P>
<P>The dump tool reads one or more LAMMPS dump files, stores their
contents as a series of snapshots with 2d arrays of atom attributes,
and allows the values to be accessed and manipulated. Other tools use
dump objects to convert LAMMPS files to other formats or visualize the
atoms.
</P>
<P>The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
</P>
<P>The map() method assigns names to columns of atom attributes. The
tselect() methods select one or more snapshots by their time stamp.
The delete() method deletes unselected timesteps so their memory is
freed up. This can be useful to do when reading snapshots
one-at-a-time for huge data sets. The aselect() methods selects atoms
within selected snapshots. The write() and scatter() methods write
selected snapshots and atoms to one or more files.
</P>
<P>The scale(), unscale(), wrap(), unwrap(), and owrap() methods change
the coordinates of all atoms with respect to the simulation box size.
The sort() method sorts atoms within snapshots by their ID or another
specified column.
</P>
<P>The set() method enables new or existing columns to be set to new
values. The minmax() method sets a column to an integer value between
the min and max values in another column; it can be used to create a
color map. The clone() method copies that column values at one
timestep to other timesteps on a per-atom basis.
</P>
<P>The time(), atom(), and vecs() methods return time or atom data as
vectors of values.
</P>
<P>The iterator() and viz() methods are called by Pizza.py tools that
visualize snapshots of atoms (e.g. gl, raster, svg tools). You can
also use the iterator() method in your scripts to loop over selected
snapshots. The atype setting determines what atom column is returned
as the atom "type" by the viz() method. The bonds() method can be
used to create a static list of bonds that are returned by the viz()
method.
</P>
<HR>
<P>Normally, <A HREF = "http://lammps.sandia.gov">LAMMPS</A> creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump files is simple. Each snapshot is formatted as
follows:
</P>
<PRE>ITEM: TIMESTEP
100
ITEM: NUMBER OF ATOMS
32
ITEM: BOX BOUNDS
0 3.35919
0 3.35919
0 7.50
ITEM: ATOMS
1 1 0 0 0
2 1 0.25 0.25 0
3 1 0.25 0 0.25
...
N 3 0.7 0.5 0.6
</PRE>
<P>The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
ATOMS" where N is the number of atoms. As the dump tool commands
indicate, atoms do not have to be listed in any particular order.
There can be a different number of atoms in each snapshot. The values
on each atom line are "ID type x y z" by default, but other quantities
can be listed in any desired order. The map() command can be used to
specify the ordering if it is not the default.
</P>
<HR>
<P><B>Usage:</B>
</P>
<PRE>d = dump("dump.one") read in one or more dump files
d = dump("dump.1 dump.2.gz") can be gzipped
d = dump("dump.*") wildcard expands to multiple files
d = dump("dump.*",0) two args = store filenames, but don't read
</PRE>
<PRE> incomplete and duplicate snapshots are deleted
atoms will be unscaled if stored in files as scaled
</PRE>
<PRE>time = d.next() read next snapshot from dump files
</PRE>
<PRE> used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment or unscaling is performed
</PRE>
<PRE>d.map(1,"id",3,"x") assign names to atom columns (1-N)
</PRE>
<PRE> not needed if dump file is self-describing
</PRE>
<PRE>d.tselect.all() select all timesteps
d.tselect.one(N) select only timestep N
d.tselect.none() deselect all timesteps
d.tselect.skip(M) select every Mth step
d.tselect.test("$t >= 100 and $t < 10000") select matching timesteps
d.delete() delete non-selected timesteps
</PRE>
<PRE> selecting a timestep also selects all atoms in the timestep
skip() and test() only select from currently selected timesteps
test() uses a Python Boolean expression with $t for timestep value
Python comparison syntax: == != < > <= >= and or
</PRE>
<PRE>d.aselect.all() select all atoms in all steps
d.aselect.all(N) select all atoms in one step
d.aselect.test("$id > 100 and $type == 2") select match atoms in all steps
d.aselect.test("$id > 100 and $type == 2",N) select matching atoms in one step
</PRE>
<PRE> all() with no args selects atoms from currently selected timesteps
test() with one arg selects atoms from currently selected timesteps
test() sub-selects from currently selected atoms
test() uses a Python Boolean expression with $ for atom attributes
Python comparison syntax: == != < > <= >= and or
$name must end with a space
</PRE>
<PRE>d.write("file") write selected steps/atoms to dump file
d.write("file",head,app) write selected steps/atoms to dump file
d.scatter("tmp") write selected steps/atoms to multiple files
</PRE>
<PRE> write() can be specified with 2 additional flags
headd = 0/1 for no/yes snapshot header, app = 0/1 for write vs append
scatter() files are given timestep suffix: e.g. tmp.0, tmp.100, etc
</PRE>
<PRE>d.scale() scale x,y,z to 0-1 for all timesteps
d.scale(100) scale atom coords for timestep N
d.unscale() unscale x,y,z to box size to all timesteps
d.unscale(1000) unscale atom coords for timestep N
d.wrap() wrap x,y,z into periodic box via ix,iy,iz
d.unwrap() unwrap x,y,z out of box via ix,iy,iz
d.owrap("other") wrap x,y,z to same image as another atom
d.sort() sort atoms by atom ID in all selected steps
d.sort("x") sort atoms by column value in all steps
d.sort(1000) sort atoms in timestep N
</PRE>
<PRE> scale(), unscale(), wrap(), unwrap(), owrap() operate on all steps and atoms
wrap(), unwrap(), owrap() require ix,iy,iz be defined
owrap() requires a column be defined which contains an atom ID
name of that column is the argument to owrap()
x,y,z for each atom is wrapped to same image as the associated atom ID
useful for wrapping all molecule's atoms the same so it is contiguous
</PRE>
<PRE>m1,m2 = d.minmax("type") find min/max values for a column
d.set("$ke = $vx * $vx + $vy * $vy") set a column to a computed value
d.setv("type",vector) set a column to a vector of values
d.spread("ke",N,"color") 2nd col = N ints spread over 1st col
d.clone(1000,"color") clone timestep N values to other steps
</PRE>
<PRE> minmax() operates on selected timesteps and atoms
set() operates on selected timesteps and atoms
left hand side column is created if necessary
left-hand side column is unset or unchanged for non-selected atoms
equation is in Python syntax
use $ for column names, $name must end with a space
setv() operates on selected timesteps and atoms
if column label does not exist, column is created
values in vector are assigned sequentially to atoms, so may want to sort()
length of vector must match # of selected atoms
spread() operates on selected timesteps and atoms
min and max are found for 1st specified column across all selected atoms
atom's value is linear mapping (1-N) between min and max
that is stored in 2nd column (created if needed)
useful for creating a color map
clone() operates on selected timesteps and atoms
values at every timestep are set to value at timestep N for that atom ID
useful for propagating a color map
</PRE>
<PRE>t = d.time() return vector of selected timestep values
fx,fy,... = d.atom(100,"fx","fy",...) return vector(s) for atom ID N
fx,fy,... = d.vecs(1000,"fx","fy",...) return vector(s) for timestep N
</PRE>
<PRE> atom() returns vectors with one value for each selected timestep
vecs() returns vectors with one value for each selected atom in the timestep
</PRE>
<PRE>index,time,flag = d.iterator(0/1) loop over dump snapshots
time,box,atoms,bonds,tris,lines = d.viz(index) return list of viz objects
d.atype = "color" set column returned as "type" by viz
d.extra(obj) extract bond/tri/line info from obj
</PRE>
<PRE> iterator() loops over selected timesteps
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = index within dump object (0 to # of snapshots)
time = timestep value
flag = -1 when iteration is done, 1 otherwise
viz() returns info for selected atoms for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
atoms = id,type,x,y,z for each atom as 2d array
bonds = id,type,x1,y1,z1,x2,y2,z2,t1,t2 for each bond as 2d array
if extra() used to define bonds, else NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
if extra() used to define tris, else NULL
lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
if extra() used to define lines, else NULL
atype is column name viz() will return as atom type (def = "type")
extra() extracts bonds/tris/lines from obj each time viz() is called
obj can be data object for bonds, cdata object for tris and lines,
bdump object for bonds, mdump object for tris, ldump object for lines
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "data.html">data</A>, <A HREF = "gl.html">gl</A>, <A HREF = "mdump.html">mdump</A>, <A HREF = "tdump.html">tdump</A>,
<A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).
</P>
</HTML>

231
doc/dump.txt Normal file
View File

@ -0,0 +1,231 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
dump tool :h3
[Purpose:]
Read, write, manipulate dump files and particle attributes.
[Description:]
The dump tool reads one or more LAMMPS dump files, stores their
contents as a series of snapshots with 2d arrays of atom attributes,
and allows the values to be accessed and manipulated. Other tools use
dump objects to convert LAMMPS files to other formats or visualize the
atoms.
The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
The map() method assigns names to columns of atom attributes. The
tselect() methods select one or more snapshots by their time stamp.
The delete() method deletes unselected timesteps so their memory is
freed up. This can be useful to do when reading snapshots
one-at-a-time for huge data sets. The aselect() methods selects atoms
within selected snapshots. The write() and scatter() methods write
selected snapshots and atoms to one or more files.
The scale(), unscale(), wrap(), unwrap(), and owrap() methods change
the coordinates of all atoms with respect to the simulation box size.
The sort() method sorts atoms within snapshots by their ID or another
specified column.
The set() method enables new or existing columns to be set to new
values. The minmax() method sets a column to an integer value between
the min and max values in another column; it can be used to create a
color map. The clone() method copies that column values at one
timestep to other timesteps on a per-atom basis.
The time(), atom(), and vecs() methods return time or atom data as
vectors of values.
The iterator() and viz() methods are called by Pizza.py tools that
visualize snapshots of atoms (e.g. gl, raster, svg tools). You can
also use the iterator() method in your scripts to loop over selected
snapshots. The atype setting determines what atom column is returned
as the atom "type" by the viz() method. The bonds() method can be
used to create a static list of bonds that are returned by the viz()
method.
:line
Normally, "LAMMPS"_http://lammps.sandia.gov creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump files is simple. Each snapshot is formatted as
follows:
ITEM: TIMESTEP
100
ITEM: NUMBER OF ATOMS
32
ITEM: BOX BOUNDS
0 3.35919
0 3.35919
0 7.50
ITEM: ATOMS
1 1 0 0 0
2 1 0.25 0.25 0
3 1 0.25 0 0.25
...
N 3 0.7 0.5 0.6 :pre
The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
ATOMS" where N is the number of atoms. As the dump tool commands
indicate, atoms do not have to be listed in any particular order.
There can be a different number of atoms in each snapshot. The values
on each atom line are "ID type x y z" by default, but other quantities
can be listed in any desired order. The map() command can be used to
specify the ordering if it is not the default.
:line
[Usage:]
d = dump("dump.one") read in one or more dump files
d = dump("dump.1 dump.2.gz") can be gzipped
d = dump("dump.*") wildcard expands to multiple files
d = dump("dump.*",0) two args = store filenames, but don't read :pre
incomplete and duplicate snapshots are deleted
atoms will be unscaled if stored in files as scaled :pre
time = d.next() read next snapshot from dump files :pre
used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment or unscaling is performed :pre
d.map(1,"id",3,"x") assign names to atom columns (1-N) :pre
not needed if dump file is self-describing :pre
d.tselect.all() select all timesteps
d.tselect.one(N) select only timestep N
d.tselect.none() deselect all timesteps
d.tselect.skip(M) select every Mth step
d.tselect.test("$t >= 100 and $t < 10000") select matching timesteps
d.delete() delete non-selected timesteps :pre
selecting a timestep also selects all atoms in the timestep
skip() and test() only select from currently selected timesteps
test() uses a Python Boolean expression with $t for timestep value
Python comparison syntax: == != < > <= >= and or :pre
d.aselect.all() select all atoms in all steps
d.aselect.all(N) select all atoms in one step
d.aselect.test("$id > 100 and $type == 2") select match atoms in all steps
d.aselect.test("$id > 100 and $type == 2",N) select matching atoms in one step :pre
all() with no args selects atoms from currently selected timesteps
test() with one arg selects atoms from currently selected timesteps
test() sub-selects from currently selected atoms
test() uses a Python Boolean expression with $ for atom attributes
Python comparison syntax: == != < > <= >= and or
$name must end with a space :pre
d.write("file") write selected steps/atoms to dump file
d.write("file",head,app) write selected steps/atoms to dump file
d.scatter("tmp") write selected steps/atoms to multiple files :pre
write() can be specified with 2 additional flags
headd = 0/1 for no/yes snapshot header, app = 0/1 for write vs append
scatter() files are given timestep suffix: e.g. tmp.0, tmp.100, etc :pre
d.scale() scale x,y,z to 0-1 for all timesteps
d.scale(100) scale atom coords for timestep N
d.unscale() unscale x,y,z to box size to all timesteps
d.unscale(1000) unscale atom coords for timestep N
d.wrap() wrap x,y,z into periodic box via ix,iy,iz
d.unwrap() unwrap x,y,z out of box via ix,iy,iz
d.owrap("other") wrap x,y,z to same image as another atom
d.sort() sort atoms by atom ID in all selected steps
d.sort("x") sort atoms by column value in all steps
d.sort(1000) sort atoms in timestep N :pre
scale(), unscale(), wrap(), unwrap(), owrap() operate on all steps and atoms
wrap(), unwrap(), owrap() require ix,iy,iz be defined
owrap() requires a column be defined which contains an atom ID
name of that column is the argument to owrap()
x,y,z for each atom is wrapped to same image as the associated atom ID
useful for wrapping all molecule's atoms the same so it is contiguous :pre
m1,m2 = d.minmax("type") find min/max values for a column
d.set("$ke = $vx * $vx + $vy * $vy") set a column to a computed value
d.setv("type",vector) set a column to a vector of values
d.spread("ke",N,"color") 2nd col = N ints spread over 1st col
d.clone(1000,"color") clone timestep N values to other steps :pre
minmax() operates on selected timesteps and atoms
set() operates on selected timesteps and atoms
left hand side column is created if necessary
left-hand side column is unset or unchanged for non-selected atoms
equation is in Python syntax
use $ for column names, $name must end with a space
setv() operates on selected timesteps and atoms
if column label does not exist, column is created
values in vector are assigned sequentially to atoms, so may want to sort()
length of vector must match # of selected atoms
spread() operates on selected timesteps and atoms
min and max are found for 1st specified column across all selected atoms
atom's value is linear mapping (1-N) between min and max
that is stored in 2nd column (created if needed)
useful for creating a color map
clone() operates on selected timesteps and atoms
values at every timestep are set to value at timestep N for that atom ID
useful for propagating a color map :pre
t = d.time() return vector of selected timestep values
fx,fy,... = d.atom(100,"fx","fy",...) return vector(s) for atom ID N
fx,fy,... = d.vecs(1000,"fx","fy",...) return vector(s) for timestep N :pre
atom() returns vectors with one value for each selected timestep
vecs() returns vectors with one value for each selected atom in the timestep :pre
index,time,flag = d.iterator(0/1) loop over dump snapshots
time,box,atoms,bonds,tris,lines = d.viz(index) return list of viz objects
d.atype = "color" set column returned as "type" by viz
d.extra(obj) extract bond/tri/line info from obj :pre
iterator() loops over selected timesteps
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = index within dump object (0 to # of snapshots)
time = timestep value
flag = -1 when iteration is done, 1 otherwise
viz() returns info for selected atoms for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \\[xlo,ylo,zlo,xhi,yhi,zhi\\]
atoms = id,type,x,y,z for each atom as 2d array
bonds = id,type,x1,y1,z1,x2,y2,z2,t1,t2 for each bond as 2d array
if extra() used to define bonds, else NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
if extra() used to define tris, else NULL
lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
if extra() used to define lines, else NULL
atype is column name viz() will return as atom type (def = "type")
extra() extracts bonds/tris/lines from obj each time viz() is called
obj can be data object for bonds, cdata object for tris and lines,
bdump object for bonds, mdump object for tris, ldump object for lines :pre
[Related tools:]
"data"_data.html, "gl"_gl.html, "mdump"_mdump.html, "tdump"_tdump.html,
"raster"_raster.html, "svg"_svg.html
[Prerequisites:]
Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).

78
doc/ensight.html Normal file
View File

@ -0,0 +1,78 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>ensight tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Convert LAMMPS snapshots or meshes to Ensight format.
</P>
<P><B>Description:</B>
</P>
<P>The ensight tool converts atom snapshots in a LAMMPS dump or data file
or mesh data from a mesh file to the format used by the <A HREF = "http://www.ensight.com">Ensight
visualization package</A>. See the <A HREF = "dump.html">dump</A> or
<A HREF = "mdump.html">mdump</A> tools for info about the format of these files and
what data they contain.
</P>
<P>The ensight constructor takes an object that stores atom or mesh
snapshots (<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>) as its first argument.
The atom snapshots must have "id", "type", "x", "y", and "z" defined;
see the map() methods of those tools.
</P>
<P>The one(), many(), and single() methods convert specific snapshots to
Ensight format and write them out. These methods take a file prefix
as an optional first argument; the prefix "tmp" will be used if not
specified. These methods all create a prefix.case file which is used
by Ensight to define the format and list all associated files. One or
more prefix*.xyz files are also produced which contain atom
coordinates sorted by atom type. If additional pairs of arguments are
specified, attributes from the shapshot data (atoms or elements) can
be written into Ensight variable files, and used by Ensight as display
attributes for the atoms or mesh elements.
</P>
<P><B>Usage:</B>
</P>
<PRE>e = ensight(d) d = object with atoms or elements (dump,data,mdump)
e.change = 1 set to 1 if element nodal xyz change with time (def = 0)
e.maxtype = 10 max particle type, set if query to data will be bad
</PRE>
<PRE>e.one()
e.one("new")
e.one("cns","Centro","eng","Energy")
e.one("new","cns","Centro","eng","Energy")
write all snapshots as an Ensight data set
Ensight header file = tmp.case (no 1st arg) or new.case
Ensight coord file = tmp.xyz or new.xyz
additional pairs of args create auxiliary files:
tmp.cns, tmp.eng or new.cns, new.eng
cns,eng = column name in dump file and file name suffix
Centro,Energy = Ensight name for the variable
</PRE>
<PRE>e.increment() same args as one(), but process dump out-of-core
</PRE>
<PRE>e.many() same args as one(), but create multiple Ensight files
tmp0000.xyz, tmp0001.xyz, etc
new0000.cns, new0001.cns, etc
new0000.eng, new0001.eng, etc
</PRE>
<PRE>e.single(N) same args as one() prepended by N, but write a single snap
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "cfg.html">cfg</A>, <A HREF = "data.html">data</A>, <A HREF = "dump.html">dump</A>,
<A HREF = "mdump.html">mdump</A>, <A HREF = "vtk.html">vtk</A>, <A HREF = "xyz.html">xyz</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

73
doc/ensight.txt Normal file
View File

@ -0,0 +1,73 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
ensight tool :h3
[Purpose:]
Convert LAMMPS snapshots or meshes to Ensight format.
[Description:]
The ensight tool converts atom snapshots in a LAMMPS dump or data file
or mesh data from a mesh file to the format used by the "Ensight
visualization package"_ensight. See the "dump"_dump.html or
"mdump"_mdump.html tools for info about the format of these files and
what data they contain.
:link(ensight,http://www.ensight.com)
The ensight constructor takes an object that stores atom or mesh
snapshots ("dump"_dump.html, "data"_data.html) as its first argument.
The atom snapshots must have "id", "type", "x", "y", and "z" defined;
see the map() methods of those tools.
The one(), many(), and single() methods convert specific snapshots to
Ensight format and write them out. These methods take a file prefix
as an optional first argument; the prefix "tmp" will be used if not
specified. These methods all create a prefix.case file which is used
by Ensight to define the format and list all associated files. One or
more prefix*.xyz files are also produced which contain atom
coordinates sorted by atom type. If additional pairs of arguments are
specified, attributes from the shapshot data (atoms or elements) can
be written into Ensight variable files, and used by Ensight as display
attributes for the atoms or mesh elements.
[Usage:]
e = ensight(d) d = object with atoms or elements (dump,data,mdump)
e.change = 1 set to 1 if element nodal xyz change with time (def = 0)
e.maxtype = 10 max particle type, set if query to data will be bad :pre
e.one()
e.one("new")
e.one("cns","Centro","eng","Energy")
e.one("new","cns","Centro","eng","Energy")
write all snapshots as an Ensight data set
Ensight header file = tmp.case (no 1st arg) or new.case
Ensight coord file = tmp.xyz or new.xyz
additional pairs of args create auxiliary files:
tmp.cns, tmp.eng or new.cns, new.eng
cns,eng = column name in dump file and file name suffix
Centro,Energy = Ensight name for the variable :pre
e.increment() same args as one(), but process dump out-of-core :pre
e.many() same args as one(), but create multiple Ensight files
tmp0000.xyz, tmp0001.xyz, etc
new0000.cns, new0001.cns, etc
new0000.eng, new0001.eng, etc :pre
e.single(N) same args as one() prepended by N, but write a single snap :pre
[Related tools:]
"cfg"_cfg.html, "data"_data.html, "dump"_dump.html,
"mdump"_mdump.html, "vtk"_vtk.html, "xyz"_xyz.html
[Prerequisites:] none

187
doc/gl.html Normal file
View File

@ -0,0 +1,187 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>gl tool
</H3>
<P><B>Purpose:</B>
</P>
<P>3d interactive visualization via OpenGL.
</P>
<P><B>Description:</B>
</P>
<P>The gl tool does visualizes LAMMPS or ChemCell snapshots or data files
and mesh files via OpenGL graphics calls. The interface to OpenGL is
provided to Python by the open-source <A HREF = "http://pyopengl.sourceforge.net">PyOpenGL
toolkit</A>. To do interactive
visualization, consider using this tool in conjunction with the
<A HREF = "vcr.html">vcr</A> tool.
</P>
<P>The gl constructor takes a data object containing atom or mesh
snapshots as an argument (<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>,
<A HREF = "cdata.html">cdata</A>, <A HREF = "mdump.html">mdump</A>).
</P>
<P>The show() method displays a single image of the selected atoms or
triangles of snapshot N and saves it as image.png. While an image is
displayed, the view can be changed directly by using the mouse buttons
in the OpenGl window to translate (left), rotate (middle), or zoom
(right) the image. However, these mouse changes are not permanent,
unless the corresponding trans(), rotate(), and zoom() methods are
invoked. The all() method loops thru all selected snapshots,
displaying each one in turn. The resulting image files are saved to
image0000.png, image0001.png, etc. The prefix "image" can be changed
via the file setting.
</P>
<P>The bg(), size(), rotate(), trans(), zoom(), box(), label(), and
nolabel() methods control various aspects of the images produced.
Without the trans() and zoom() settings, the GL image should roughly
fill the window and be centered.
</P>
<P>Additional movie effects can be produced using the pan() and select()
methods. The pan() method specifies an initial and final viewpoint
that is applied to the images produced by the all() method. For
intermediate images, the view parameters will be interpolated between
their initial and final values. The pan() method can thus be used to
rotate a single image or fly-by the simulation as it animates. The
select() method performs additional atom selection for each image of
the all() sequence. An image-dependent %g variable can be used in the
select() string. The select() method can thus be used to slice thru
the data set.
</P>
<P>The acol(), arad(), bcol(), brad(), tcol(), and tfill() methods change
attributes of the atoms, bonds, and triangles displayed. Each atom or
bond returned from the data object has an integer "type" from 1 to N.
The type is used to index into a list of RGB colors or radii for atoms
and bond thickness. The adef(), bdef(), and tdef() methods setup
default mappings of types to colors/radii. The other methods enable
specific assignments to be made. The interpolation option (e.g. many
types assigned to a few colors), enables a smooth rainbow of colors to
be assigned to a range of types. Note that the <A HREF = "dump.html">dump</A> tool
allows any vector to be returned as an atom "type" via its atype
setting. Thus displayed colors can be keyed to atom velocity or other
properties.
</P>
<P>Colors are specified with a string, e.g. "red". There are 140
pre-defined colors from <A HREF = "http://www.oreilly.com/catalog/wdnut/excerpt/color_names.html">this WWW page</A> which can be
examined by importing the "colors" variable from "vizinfo". New
colors can be defined by assigning a nickname of your choice to an RGB
triplet, as described below.
</P>
<P>The visual quality of atom spheres can be set via the q() method. The
axis() method toggles whether xyz axes are displayed in the OpenGL
window. Red is the +x axis, green is +y, and blue is +z. The ortho()
method toggles between an orthographic and perspective display of the
snapshot. The clip() method can be used to narrow the amount of data
that is visualized. The reload() method is needed if you change the
selection attributes of the underlying data assigned to the
<A HREF = "gl.html">gl</A> tool, such as via the <A HREF = "dump.html">dump</A> tool's methods.
These changes will not be visible in the OpenGL window until the data
is reloaded.
</P>
<P><B>Usage:</B>
</P>
<PRE>g = gl(d) create OpenGL display for data in d
</PRE>
<PRE> d = atom snapshot object (dump, data)
</PRE>
<PRE>g.bg("black") set background color (def = "black")
g.size(N) set image size to NxN
g.size(N,M) set image size to NxM
g.rotate(60,135) view from z theta and azimuthal phi (def = 60,30)
g.shift(x,y) translate by x,y pixels in view window (def = 0,0)
g.zoom(0.5) scale image by factor (def = 1)
g.box(0/1/2) 0/1/2 = none/variable/fixed box
g.box(0/1/2,"green") set box color
g.box(0/1/2,"red",4) set box edge thickness
g.file = "image" file prefix for created images (def = "image")
</PRE>
<PRE>g.show(N) show image of snapshot at timestep N
</PRE>
<PRE>g.all() make images of all selected snapshots
g.all(P) images of all, start file label at P
g.all(N,M,P) make M images of snapshot N, start label at P
</PRE>
<PRE>g.pan(60,135,1.0,40,135,1.5) pan during all() operation
g.pan() no pan during all() (default)
</PRE>
<PRE> args = z theta, azimuthal phi, zoom factor at beginning and end
values at each step are interpolated between beginning and end values
</PRE>
<PRE>g.select = "$x > %g*3.0" string to pass to d.aselect.test() during all()
g.select = "" no extra aselect (default)
</PRE>
<PRE> %g varies from 0.0 to 1.0 from beginning to end of all()
</PRE>
<PRE>g.acol(2,"green") set atom colors by atom type (1-N)
g.acol([2,4],["red","blue"]) 1st arg = one type or list of types
g.acol(0,"blue") 2nd arg = one color or list of colors
g.acol(range(20),["red","blue"]) if list lengths unequal, interpolate
g.acol(range(10),"loop") assign colors in loop, randomly ordered
</PRE>
<PRE> if 1st arg is 0, set all types to 2nd arg
if list of types has a 0 (e.g. range(10)), +1 is added to each value
interpolate means colors blend smoothly from one value to the next
</PRE>
<PRE>g.arad([1,2],[0.5,0.3]) set atom radii, same rules as acol()
</PRE>
<PRE>g.bcol() set bond color, same args as acol()
g.brad() set bond thickness, same args as arad()
</PRE>
<PRE>g.tcol() set triangle color, same args as acol()
g.tfill() set triangle fill, 0 fill, 1 line, 2 both
</PRE>
<PRE>g.lcol() set line color, same args as acol()
g.lrad() set line thickness, same args as arad()
</PRE>
<PRE>g.adef() set atom/bond/tri/line properties to default
g.bdef() default = "loop" for colors, 0.45 for radii
g.tdef() default = 0.25 for bond/line thickness
g.ldef() default = 0 fill
</PRE>
<PRE> by default 100 types are assigned
if atom/bond/tri/line has type > # defined properties, is an error
</PRE>
<PRE>from vizinfo import colors access color list
print colors list defined color names and RGB values
colors["nickname"] = [R,G,B] set new RGB values from 0 to 255
</PRE>
<PRE> 140 pre-defined colors: red, green, blue, purple, yellow, black, white, etc
</PRE>
<PRE>Settings specific to gl tool:
</PRE>
<PRE>g.q(10) set quality of image (def = 5)
g.axis(0/1) turn xyz axes off/on
g.ortho(0/1) perspective (0) vs orthographic (1) view
g.clip('xlo',0.25) clip in xyz from lo/hi at box fraction (0-1)
g.reload() force all data to be reloaded
g.cache = 0/1 turn off/on GL cache lists (def = on)
theta,phi,x,y,scale,up = g.gview() grab all current view parameters
g.sview(theta,phi,x,y,scale,up) set all view parameters
</PRE>
<PRE> data reload is necessary if dump selection is used to change the data
cache lists usually improve graphics performance
gview returns values to use in other commands:
theta,phi are args to rotate()
x,y are args to shift()
scale is arg to zoom()
up is a 3-vector arg to sview()
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "rasmol.html">rasmol</A>, <A HREF = "raster.html">raster</A>,
<A HREF = "svg.html">svg</A>, <A HREF = "vcr.html">vcr</A>, <A HREF = "vmd.html">vmd</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Python PyOpenGL and PIL packages.
</P>
</HTML>

182
doc/gl.txt Normal file
View File

@ -0,0 +1,182 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
gl tool :h3
[Purpose:]
3d interactive visualization via OpenGL.
[Description:]
The gl tool does visualizes LAMMPS or ChemCell snapshots or data files
and mesh files via OpenGL graphics calls. The interface to OpenGL is
provided to Python by the open-source "PyOpenGL
toolkit"_http://pyopengl.sourceforge.net. To do interactive
visualization, consider using this tool in conjunction with the
"vcr"_vcr.html tool.
The gl constructor takes a data object containing atom or mesh
snapshots as an argument ("dump"_dump.html, "data"_data.html,
"cdata"_cdata.html, "mdump"_mdump.html).
The show() method displays a single image of the selected atoms or
triangles of snapshot N and saves it as image.png. While an image is
displayed, the view can be changed directly by using the mouse buttons
in the OpenGl window to translate (left), rotate (middle), or zoom
(right) the image. However, these mouse changes are not permanent,
unless the corresponding trans(), rotate(), and zoom() methods are
invoked. The all() method loops thru all selected snapshots,
displaying each one in turn. The resulting image files are saved to
image0000.png, image0001.png, etc. The prefix "image" can be changed
via the file setting.
The bg(), size(), rotate(), trans(), zoom(), box(), label(), and
nolabel() methods control various aspects of the images produced.
Without the trans() and zoom() settings, the GL image should roughly
fill the window and be centered.
Additional movie effects can be produced using the pan() and select()
methods. The pan() method specifies an initial and final viewpoint
that is applied to the images produced by the all() method. For
intermediate images, the view parameters will be interpolated between
their initial and final values. The pan() method can thus be used to
rotate a single image or fly-by the simulation as it animates. The
select() method performs additional atom selection for each image of
the all() sequence. An image-dependent %g variable can be used in the
select() string. The select() method can thus be used to slice thru
the data set.
The acol(), arad(), bcol(), brad(), tcol(), and tfill() methods change
attributes of the atoms, bonds, and triangles displayed. Each atom or
bond returned from the data object has an integer "type" from 1 to N.
The type is used to index into a list of RGB colors or radii for atoms
and bond thickness. The adef(), bdef(), and tdef() methods setup
default mappings of types to colors/radii. The other methods enable
specific assignments to be made. The interpolation option (e.g. many
types assigned to a few colors), enables a smooth rainbow of colors to
be assigned to a range of types. Note that the "dump"_dump.html tool
allows any vector to be returned as an atom "type" via its atype
setting. Thus displayed colors can be keyed to atom velocity or other
properties.
Colors are specified with a string, e.g. "red". There are 140
pre-defined colors from "this WWW page"_colortable which can be
examined by importing the "colors" variable from "vizinfo". New
colors can be defined by assigning a nickname of your choice to an RGB
triplet, as described below.
:link(colortable,http://www.oreilly.com/catalog/wdnut/excerpt/color_names.html)
The visual quality of atom spheres can be set via the q() method. The
axis() method toggles whether xyz axes are displayed in the OpenGL
window. Red is the +x axis, green is +y, and blue is +z. The ortho()
method toggles between an orthographic and perspective display of the
snapshot. The clip() method can be used to narrow the amount of data
that is visualized. The reload() method is needed if you change the
selection attributes of the underlying data assigned to the
"gl"_gl.html tool, such as via the "dump"_dump.html tool's methods.
These changes will not be visible in the OpenGL window until the data
is reloaded.
[Usage:]
g = gl(d) create OpenGL display for data in d :pre
d = atom snapshot object (dump, data) :pre
g.bg("black") set background color (def = "black")
g.size(N) set image size to NxN
g.size(N,M) set image size to NxM
g.rotate(60,135) view from z theta and azimuthal phi (def = 60,30)
g.shift(x,y) translate by x,y pixels in view window (def = 0,0)
g.zoom(0.5) scale image by factor (def = 1)
g.box(0/1/2) 0/1/2 = none/variable/fixed box
g.box(0/1/2,"green") set box color
g.box(0/1/2,"red",4) set box edge thickness
g.file = "image" file prefix for created images (def = "image") :pre
g.show(N) show image of snapshot at timestep N :pre
g.all() make images of all selected snapshots
g.all(P) images of all, start file label at P
g.all(N,M,P) make M images of snapshot N, start label at P :pre
g.pan(60,135,1.0,40,135,1.5) pan during all() operation
g.pan() no pan during all() (default) :pre
args = z theta, azimuthal phi, zoom factor at beginning and end
values at each step are interpolated between beginning and end values :pre
g.select = "$x > %g*3.0" string to pass to d.aselect.test() during all()
g.select = "" no extra aselect (default) :pre
%g varies from 0.0 to 1.0 from beginning to end of all() :pre
g.acol(2,"green") set atom colors by atom type (1-N)
g.acol(\[2,4\],\["red","blue"\]) 1st arg = one type or list of types
g.acol(0,"blue") 2nd arg = one color or list of colors
g.acol(range(20),\["red","blue"\]) if list lengths unequal, interpolate
g.acol(range(10),"loop") assign colors in loop, randomly ordered :pre
if 1st arg is 0, set all types to 2nd arg
if list of types has a 0 (e.g. range(10)), +1 is added to each value
interpolate means colors blend smoothly from one value to the next :pre
g.arad(\[1,2\],\[0.5,0.3\]) set atom radii, same rules as acol() :pre
g.bcol() set bond color, same args as acol()
g.brad() set bond thickness, same args as arad() :pre
g.tcol() set triangle color, same args as acol()
g.tfill() set triangle fill, 0 fill, 1 line, 2 both :pre
g.lcol() set line color, same args as acol()
g.lrad() set line thickness, same args as arad() :pre
g.adef() set atom/bond/tri/line properties to default
g.bdef() default = "loop" for colors, 0.45 for radii
g.tdef() default = 0.25 for bond/line thickness
g.ldef() default = 0 fill :pre
by default 100 types are assigned
if atom/bond/tri/line has type > # defined properties, is an error :pre
from vizinfo import colors access color list
print colors list defined color names and RGB values
colors\["nickname"\] = \[R,G,B\] set new RGB values from 0 to 255 :pre
140 pre-defined colors: red, green, blue, purple, yellow, black, white, etc :pre
Settings specific to gl tool: :pre
g.q(10) set quality of image (def = 5)
g.axis(0/1) turn xyz axes off/on
g.ortho(0/1) perspective (0) vs orthographic (1) view
g.clip('xlo',0.25) clip in xyz from lo/hi at box fraction (0-1)
g.reload() force all data to be reloaded
g.cache = 0/1 turn off/on GL cache lists (def = on)
theta,phi,x,y,scale,up = g.gview() grab all current view parameters
g.sview(theta,phi,x,y,scale,up) set all view parameters :pre
data reload is necessary if dump selection is used to change the data
cache lists usually improve graphics performance
gview returns values to use in other commands:
theta,phi are args to rotate()
x,y are args to shift()
scale is arg to zoom()
up is a 3-vector arg to sview() :pre
[Related tools:]
"dump"_dump.html, "rasmol"_rasmol.html, "raster"_raster.html,
"svg"_svg.html, "vcr"_vcr.html, "vmd"_vmd.html
[Prerequisites:]
Python PyOpenGL and PIL packages.

116
doc/gnu.html Normal file
View File

@ -0,0 +1,116 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>gnu tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Create plots via GnuPlot plotting program.
</P>
<P><B>Description:</B>
</P>
<P>The gnu tool is a wrapper on the <A HREF = "http://www.gnuplot.info/">GnuPlot</A>
plotting package. GnuPlot is open source software and runs on any
platform.
</P>
<P>The gnu constructor launches GnuPlot as a process which the gnu tool
sends commands to. The GnuPlot process can be killed via the stop()
method, though this is typically unnecessary.
</P>
<P>The plot() method plots a single vector against a linear index or
pairs of vectors against each other. The pairs of vectors are written
to files and read-in by GnuPlot's plot command.
</P>
<P>The mplot() method creates a series of plots and saves them each to a
numbered file. Each file is a plot of an increasing portion of the
vector(s). This can be used to make an animation of a plot.
</P>
<P>The enter() method can be used to interact with GnuPlot directly.
Each subsequent line you type is a GnuPlot command, until you type
"quit" or "exit" to return to Pizza.py. Single GnuPlot commands can
be issued as string arguments to the gnu tool.
</P>
<P>The export() method writes numeric data as columns to text files, so
that GnuPlot can read them via its "plot" command.
</P>
<P>Mutliple windows can be displayed, plotted to, and manipulated using
the select() and hide() methods. The save() method writes the
currently selected plot to a PostScript file.
</P>
<P>The remaining methods (aspect, title, xrange, etc) set attributes of
the currently selected plot. The erase() method resets all attributes
to their default values.
</P>
<P><B>Usage:</B>
</P>
<PRE>g = gnu() start up GnuPlot
g.stop() shut down GnuPlot process
</PRE>
<PRE>g.plot(a) plot vector A against linear index
g.plot(a,b) plot B against A
g.plot(a,b,c,d,...) plot B against A, D against C, etc
g.mplot(M,N,S,"file",a,b,...) multiple plots saved to file0000.eps, etc
</PRE>
<PRE> each plot argument can be a tuple, list, or Numeric/NumPy vector
mplot loops over range(M,N,S) and create one plot per iteration
last args are same as list of vectors for plot(), e.g. 1, 2, 4 vectors
each plot is made from a portion of the vectors, depending on loop index i
Ith plot is of b[0:i] vs a[0:i], etc
series of plots saved as file0000.eps, file0001.eps, etc
if use xrange(),yrange() then plot axes will be same for all plots
</PRE>
<PRE>g("plot 'file.dat' using 2:3 with lines") execute string in GnuPlot
</PRE>
<PRE>g.enter() enter GnuPlot shell
gnuplot> plot sin(x) with lines type commands directly to GnuPlot
gnuplot> exit, quit exit GnuPlot shell
</PRE>
<PRE>g.export("data",range(100),a,...) create file with columns of numbers
</PRE>
<PRE> all vectors must be of equal length
could plot from file with GnuPlot command: plot 'data' using 1:2 with lines
</PRE>
<PRE>g.select(N) figure N becomes the current plot
</PRE>
<PRE> subsequent commands apply to this plot
</PRE>
<PRE>g.hide(N) delete window for figure N
g.save("file") save current plot as file.eps
</PRE>
<PRE>Set attributes for current plot:
</PRE>
<PRE>g.erase() reset all attributes to default values
g.aspect(1.3) aspect ratio
g.xtitle("Time") x axis text
g.ytitle("Energy") y axis text
g.title("My Plot") title text
g.title("title","x","y") title, x axis, y axis text
g.xrange(xmin,xmax) x axis range
g.xrange() default x axis range
g.yrange(ymin,ymax) y axis range
g.yrange() default y axis range
g.xlog() toggle x axis between linear and log
g.ylog() toggle y axis between linear and log
g.label(x,y,"text") place label at x,y coords
g.curve(N,'r') set color of curve N
</PRE>
<PRE> colors: 'k' = black, 'r' = red, 'g' = green, 'b' = blue
'm' = magenta, 'c' = cyan, 'y' = yellow
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "matlab.html">matlab</A>, <A HREF = "plotview.html">plotview</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>GnuPlot plotting package.
</P>
</HTML>

111
doc/gnu.txt Normal file
View File

@ -0,0 +1,111 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
gnu tool :h3
[Purpose:]
Create plots via GnuPlot plotting program.
[Description:]
The gnu tool is a wrapper on the "GnuPlot"_http://www.gnuplot.info/
plotting package. GnuPlot is open source software and runs on any
platform.
The gnu constructor launches GnuPlot as a process which the gnu tool
sends commands to. The GnuPlot process can be killed via the stop()
method, though this is typically unnecessary.
The plot() method plots a single vector against a linear index or
pairs of vectors against each other. The pairs of vectors are written
to files and read-in by GnuPlot's plot command.
The mplot() method creates a series of plots and saves them each to a
numbered file. Each file is a plot of an increasing portion of the
vector(s). This can be used to make an animation of a plot.
The enter() method can be used to interact with GnuPlot directly.
Each subsequent line you type is a GnuPlot command, until you type
"quit" or "exit" to return to Pizza.py. Single GnuPlot commands can
be issued as string arguments to the gnu tool.
The export() method writes numeric data as columns to text files, so
that GnuPlot can read them via its "plot" command.
Mutliple windows can be displayed, plotted to, and manipulated using
the select() and hide() methods. The save() method writes the
currently selected plot to a PostScript file.
The remaining methods (aspect, title, xrange, etc) set attributes of
the currently selected plot. The erase() method resets all attributes
to their default values.
[Usage:]
g = gnu() start up GnuPlot
g.stop() shut down GnuPlot process :pre
g.plot(a) plot vector A against linear index
g.plot(a,b) plot B against A
g.plot(a,b,c,d,...) plot B against A, D against C, etc
g.mplot(M,N,S,"file",a,b,...) multiple plots saved to file0000.eps, etc :pre
each plot argument can be a tuple, list, or Numeric/NumPy vector
mplot loops over range(M,N,S) and create one plot per iteration
last args are same as list of vectors for plot(), e.g. 1, 2, 4 vectors
each plot is made from a portion of the vectors, depending on loop index i
Ith plot is of b\[0:i\] vs a\[0:i\], etc
series of plots saved as file0000.eps, file0001.eps, etc
if use xrange(),yrange() then plot axes will be same for all plots :pre
g("plot 'file.dat' using 2:3 with lines") execute string in GnuPlot :pre
g.enter() enter GnuPlot shell
gnuplot> plot sin(x) with lines type commands directly to GnuPlot
gnuplot> exit, quit exit GnuPlot shell :pre
g.export("data",range(100),a,...) create file with columns of numbers :pre
all vectors must be of equal length
could plot from file with GnuPlot command: plot 'data' using 1:2 with lines :pre
g.select(N) figure N becomes the current plot :pre
subsequent commands apply to this plot :pre
g.hide(N) delete window for figure N
g.save("file") save current plot as file.eps :pre
Set attributes for current plot: :pre
g.erase() reset all attributes to default values
g.aspect(1.3) aspect ratio
g.xtitle("Time") x axis text
g.ytitle("Energy") y axis text
g.title("My Plot") title text
g.title("title","x","y") title, x axis, y axis text
g.xrange(xmin,xmax) x axis range
g.xrange() default x axis range
g.yrange(ymin,ymax) y axis range
g.yrange() default y axis range
g.xlog() toggle x axis between linear and log
g.ylog() toggle y axis between linear and log
g.label(x,y,"text") place label at x,y coords
g.curve(N,'r') set color of curve N :pre
colors: 'k' = black, 'r' = red, 'g' = green, 'b' = blue
'm' = magenta, 'c' = cyan, 'y' = yellow :pre
[Related tools:]
"matlab"_matlab.html, "plotview"_plotview.html
[Prerequisites:]
GnuPlot plotting package.

45
doc/histo.html Normal file
View File

@ -0,0 +1,45 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>histo tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Particle density histogram from a dump.
</P>
<P><B>Description:</B>
</P>
<P>The histo tool creates spatial histograms of particle snapshots in
a dump file.
</P>
<P>The histo constructor takes an object that stores atom snapshots
(<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>) as its argument.
</P>
<P>The compute() method creates a histogram in a specific dimension at a
desired resolution, averaged across all selected snapshots and atoms
in the dump. The returned vectors can be plotted; x is the distance
along the chosen dimension, y is the histogram counts.
</P>
<P><B>Usage:</B>
</P>
<PRE>h = histo(d) d = dump/cdump object
</PRE>
<PRE>x,y = h.compute('x',N,lo,hi) compute histogram in dim with N bins
</PRE>
<PRE> lo/hi are optional, if not used histo will be over entire box
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

40
doc/histo.txt Normal file
View File

@ -0,0 +1,40 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
histo tool :h3
[Purpose:]
Particle density histogram from a dump.
[Description:]
The histo tool creates spatial histograms of particle snapshots in
a dump file.
The histo constructor takes an object that stores atom snapshots
("dump"_dump.html, "data"_data.html) as its argument.
The compute() method creates a histogram in a specific dimension at a
desired resolution, averaged across all selected snapshots and atoms
in the dump. The returned vectors can be plotted; x is the distance
along the chosen dimension, y is the histogram counts.
[Usage:]
h = histo(d) d = dump/cdump object :pre
x,y = h.compute('x',N,lo,hi) compute histogram in dim with N bins :pre
lo/hi are optional, if not used histo will be over entire box :pre
[Related tools:]
"dump"_dump.html
[Prerequisites:] none

91
doc/image.html Normal file
View File

@ -0,0 +1,91 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>image tool
</H3>
<P><B>Purpose:</B>
</P>
<P>View and manipulate images.
</P>
<P><B>Description:</B>
</P>
<P>The image tool can be used to display image files or convert them to
other formats via the ImageMagick tools (or alternate tools if
specified in the DEFAULTS.py file).
</P>
<P>The image constructor creates a GUI to view a set of image files as a
palette of thumbnail-size images. Each thumbnail can be clicked on to
view the full-size image. Clicking on the full-size image removes it.
The view() method does the same operation for a new set of files.
</P>
<P>The convert() method invokes the ImageMagick "convert" command to
convert an image file to a different format. If both arguments have a
wildcard character, one conversion is done for each file in the 1st
argument to create a file in the 2nd argument, e.g. "convert
image0012.svg new0012.png". If either argument has no wildcard, one
"convert" command is issued using both arguments. This form can be
used to create a movie file, e.g. "convert *.png ligand.mpg".
</P>
<P>The montage() method invokes the ImageMagick "montage" command to
combine 2 image files to create a 3rd. If all 3 arguments have a
wildcard character, one montage is created for each file in the 1st
argument, paired with one file in the 2nd argument, e.g. "montage
image0012.svg plot0012.eps combine0012.png". For this to work, the
1st arguments must each expand to the same number of files. If any of
the 3 arguments does not have a wildcard, one "montage" command is
issued using all 3 arguements.
</P>
<P>Image files can be in any format (PNG, GIF, JPG, etc) recognized by
the Python Image Library (PIL) installed in your Python or by
ImageMagick. Various Pizza.py visualization tools (raster, deja,
rasmol, etc) create such image files. If a particular image format
fails to load, your PIL installation was linked without support for
that format. Rebuild PIL, and follow the install instructions
included in its top directory.
</P>
<P><B>Usage:</B>
</P>
<PRE>i = image("my1.gif my2.gif") display thumbnails of matching images
i = image("*.png *.gif") wildcards allowed
i = image("") blank string matches all image suffixes
i = image() no display window opened if no arg
</PRE>
<PRE> image suffixes for blank string = *.png, *.bmp, *.gif, *.tiff, *.tif
click on a thumbnail to view it full-size
click on thumbnail again to remove full-sized version
</PRE>
<PRE>i.view("*.png *.gif") display thumbnails of matching images
</PRE>
<PRE> view arg is same as constructor arg
</PRE>
<PRE>i.convert("image*.svg","new*.png") each SVG file to PNG
i.convert("image*.svg","new*.jpg","-quality 50") 3rd arg is switch
i.convert("image*.png","movie.mpg") all PNGs to MPG movie
i.convert("image*.png","movie.mpg","-resize 128x128") 3rd arg is switch
i.montage("","image*.png","plot*.png","two*.png") image + plot = two
i.montage("-geometry 512x512","i*.png","new.png") 1st arg is switch
</PRE>
<PRE> convert with 2 wildcard args loops over 1st set of files to make 2nd set
convert with not all wildcard args will issue single convert command
montage with all wildcard args loops over 1st set of files,
combines with one file from other sets, to make last set of files
montage with not all wildcard args will issue single montage command
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "raster.html">raster</A>, <A HREF = "rasmol.html">rasmol</A>, <A HREF = "animate.html">animate</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Python Tkinter, Pmw, and PIL packages. ImageMagick convert and
montage commands or equivalent.
</P>
</HTML>

86
doc/image.txt Normal file
View File

@ -0,0 +1,86 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
image tool :h3
[Purpose:]
View and manipulate images.
[Description:]
The image tool can be used to display image files or convert them to
other formats via the ImageMagick tools (or alternate tools if
specified in the DEFAULTS.py file).
The image constructor creates a GUI to view a set of image files as a
palette of thumbnail-size images. Each thumbnail can be clicked on to
view the full-size image. Clicking on the full-size image removes it.
The view() method does the same operation for a new set of files.
The convert() method invokes the ImageMagick "convert" command to
convert an image file to a different format. If both arguments have a
wildcard character, one conversion is done for each file in the 1st
argument to create a file in the 2nd argument, e.g. "convert
image0012.svg new0012.png". If either argument has no wildcard, one
"convert" command is issued using both arguments. This form can be
used to create a movie file, e.g. "convert *.png ligand.mpg".
The montage() method invokes the ImageMagick "montage" command to
combine 2 image files to create a 3rd. If all 3 arguments have a
wildcard character, one montage is created for each file in the 1st
argument, paired with one file in the 2nd argument, e.g. "montage
image0012.svg plot0012.eps combine0012.png". For this to work, the
1st arguments must each expand to the same number of files. If any of
the 3 arguments does not have a wildcard, one "montage" command is
issued using all 3 arguements.
Image files can be in any format (PNG, GIF, JPG, etc) recognized by
the Python Image Library (PIL) installed in your Python or by
ImageMagick. Various Pizza.py visualization tools (raster, deja,
rasmol, etc) create such image files. If a particular image format
fails to load, your PIL installation was linked without support for
that format. Rebuild PIL, and follow the install instructions
included in its top directory.
[Usage:]
i = image("my1.gif my2.gif") display thumbnails of matching images
i = image("*.png *.gif") wildcards allowed
i = image("") blank string matches all image suffixes
i = image() no display window opened if no arg :pre
image suffixes for blank string = *.png, *.bmp, *.gif, *.tiff, *.tif
click on a thumbnail to view it full-size
click on thumbnail again to remove full-sized version :pre
i.view("*.png *.gif") display thumbnails of matching images :pre
view arg is same as constructor arg :pre
i.convert("image*.svg","new*.png") each SVG file to PNG
i.convert("image*.svg","new*.jpg","-quality 50") 3rd arg is switch
i.convert("image*.png","movie.mpg") all PNGs to MPG movie
i.convert("image*.png","movie.mpg","-resize 128x128") 3rd arg is switch
i.montage("","image*.png","plot*.png","two*.png") image + plot = two
i.montage("-geometry 512x512","i*.png","new.png") 1st arg is switch :pre
convert with 2 wildcard args loops over 1st set of files to make 2nd set
convert with not all wildcard args will issue single convert command
montage with all wildcard args loops over 1st set of files,
combines with one file from other sets, to make last set of files
montage with not all wildcard args will issue single montage command :pre
[Related tools:]
"raster"_raster.html, "rasmol"_rasmol.html, "animate"_animate.html
[Prerequisites:]
Python Tkinter, Pmw, and PIL packages. ImageMagick convert and
montage commands or equivalent.

121
doc/ldump.html Normal file
View File

@ -0,0 +1,121 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>ldump tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read dump files with line segment info.
</P>
<P><B>Description:</B>
</P>
<P>The ldump tool reads one or more LAMMPS dump files, and stores their
contents as a series of snapshots with 2d arrays of atom attributes.
It is assumed that each atom contains line segment info from a 2d
LAMMPS simulation using atom_style line. Other tools use ldump
objects to extract line segment info for visualization, like the dump
tool via its extra() method.
</P>
<P>The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
</P>
<P>The map() method assigns names to columns of atom attributes.
The id,type,end1x,end1y,end2x,end2y names must be assigned
in order for line segment info to be extracted.
</P>
<P>The viz() method is called by Pizza.py tools that visualize snapshots
of atoms (e.g. gl, raster, svg tools).
</P>
<HR>
<P>Normally, <A HREF = "http://lammps.sandia.gov">LAMMPS</A> creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump files is simple. Each snapshot is formatted as
follows:
</P>
<PRE>ITEM: TIMESTEP
100
ITEM: NUMBER OF ATOMS
32
ITEM: BOX BOUNDS
0 3.35919
0 3.35919
0 7.50
ITEM: ATOMS
1 1 0 0 0
2 1 0.25 0.25 0
3 1 0.25 0 0.25
...
N 3 0.7 0.5 0.6
</PRE>
<P>The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
ATOMS" where N is the number of atoms. Atoms do not have to be listed
in any particular order. There can be a different number of atoms in
each snapshot. Each line must contain the atom ID, type, and the end
points of the associated line segment, as specified by the map()
command.
</P>
<HR>
<P><B>Usage:</B>
</P>
<PRE>l = ldump("dump.one") read in one or more dump files
l = ldump("dump.1 dump.2.gz") can be gzipped
l = ldump("dump.*") wildcard expands to multiple files
l = ldump("dump.*",0) two args = store filenames, but don't read
</PRE>
<PRE> incomplete and duplicate snapshots are deleted
no column name assignment is performed
</PRE>
<PRE>time = l.next() read next snapshot from dump files
</PRE>
<PRE> used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment is performed
</PRE>
<PRE>l.map(1,"id",3,"x") assign names to atom columns (1-N)
</PRE>
<PRE> must assign id,type,end1x,end1y,end2x,end2y
</PRE>
<PRE>time,box,atoms,bonds,tris,lines = l.viz(index) return list of viz objects
</PRE>
<PRE> viz() returns line info for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
atoms = NULL
bonds = NULL
tris = NULL
lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
id,type are from associated atom
</PRE>
<PRE>l.owrap(...) wrap lines to same image as their atoms
</PRE>
<PRE> owrap() is called by dump tool's owrap()
useful for wrapping all molecule's atoms/lines the same so it is contiguous
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "gl.html">gl</A>, <A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).
</P>
</HTML>

116
doc/ldump.txt Normal file
View File

@ -0,0 +1,116 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
ldump tool :h3
[Purpose:]
Read dump files with line segment info.
[Description:]
The ldump tool reads one or more LAMMPS dump files, and stores their
contents as a series of snapshots with 2d arrays of atom attributes.
It is assumed that each atom contains line segment info from a 2d
LAMMPS simulation using atom_style line. Other tools use ldump
objects to extract line segment info for visualization, like the dump
tool via its extra() method.
The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
The map() method assigns names to columns of atom attributes.
The id,type,end1x,end1y,end2x,end2y names must be assigned
in order for line segment info to be extracted.
The viz() method is called by Pizza.py tools that visualize snapshots
of atoms (e.g. gl, raster, svg tools).
:line
Normally, "LAMMPS"_http://lammps.sandia.gov creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump files is simple. Each snapshot is formatted as
follows:
ITEM: TIMESTEP
100
ITEM: NUMBER OF ATOMS
32
ITEM: BOX BOUNDS
0 3.35919
0 3.35919
0 7.50
ITEM: ATOMS
1 1 0 0 0
2 1 0.25 0.25 0
3 1 0.25 0 0.25
...
N 3 0.7 0.5 0.6 :pre
The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
ATOMS" where N is the number of atoms. Atoms do not have to be listed
in any particular order. There can be a different number of atoms in
each snapshot. Each line must contain the atom ID, type, and the end
points of the associated line segment, as specified by the map()
command.
:line
[Usage:]
l = ldump("dump.one") read in one or more dump files
l = ldump("dump.1 dump.2.gz") can be gzipped
l = ldump("dump.*") wildcard expands to multiple files
l = ldump("dump.*",0) two args = store filenames, but don't read :pre
incomplete and duplicate snapshots are deleted
no column name assignment is performed :pre
time = l.next() read next snapshot from dump files :pre
used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment is performed :pre
l.map(1,"id",3,"x") assign names to atom columns (1-N) :pre
must assign id,type,end1x,end1y,end2x,end2y :pre
time,box,atoms,bonds,tris,lines = l.viz(index) return list of viz objects :pre
viz() returns line info for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \\[xlo,ylo,zlo,xhi,yhi,zhi\\]
atoms = NULL
bonds = NULL
tris = NULL
lines = id,type,x1,y1,z1,x2,y2,z2 for each line as 2d array
id,type are from associated atom :pre
l.owrap(...) wrap lines to same image as their atoms :pre
owrap() is called by dump tool's owrap()
useful for wrapping all molecule's atoms/lines the same so it is contiguous :pre
[Related tools:]
"dump"_dump.html, "gl"_gl.html, "raster"_raster.html, "svg"_svg.html
[Prerequisites:]
Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).

64
doc/log.html Normal file
View File

@ -0,0 +1,64 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>log tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read LAMMPS log files and extract thermodynamic data.
</P>
<P><B>Description:</B>
</P>
<P>Read one or more LAMMPS log files and combine their thermodynamic data
into long, named vectors (versus time). The vectors can be used in
Python for further processing and plotting, or they can be output to a
file.
</P>
<P>The log constructor reads one or more log files. If 2 arguments are
specified, a single file is specified, and it can be read
incrementally (e.g. as it is created) by the next() method.
</P>
<P>The nvec, nlen, and names values give the # of vectors, their length,
and names. The get() method returns one of more vectors as a Python
list. The write() method outputs the numeric vectors to a file.
</P>
<P><B>Usage:</B>
</P>
<PRE>l = log("file1") read in one or more log files
l = log("log1 log2.gz") can be gzipped
l = log("file*") wildcard expands to multiple files
l = log("log.lammps",0) two args = store filename, but don't read
</PRE>
<PRE> incomplete and duplicate thermo entries are deleted
</PRE>
<PRE>time = l.next() read new thermo info from file
</PRE>
<PRE> used with 2-argument constructor to allow reading thermo incrementally
return time stamp of last thermo read
return -1 if no new thermo since last read
</PRE>
<PRE>nvec = l.nvec # of vectors of thermo info
nlen = l.nlen length of each vectors
names = l.names list of vector names
t,pe,... = l.get("Time","KE",...) return one or more vectors of values
l.write("file.txt") write all vectors to a file
l.write("file.txt","Time","PE",...) write listed vectors to a file
</PRE>
<PRE> get and write allow abbreviated (uniquely) vector names
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "clog.html">clog</A>, <A HREF = "plotview.html">plotview</A>, <A HREF = "gnu.html">gnu</A>,
<A HREF = "matlab.html">matlab</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

59
doc/log.txt Normal file
View File

@ -0,0 +1,59 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
log tool :h3
[Purpose:]
Read LAMMPS log files and extract thermodynamic data.
[Description:]
Read one or more LAMMPS log files and combine their thermodynamic data
into long, named vectors (versus time). The vectors can be used in
Python for further processing and plotting, or they can be output to a
file.
The log constructor reads one or more log files. If 2 arguments are
specified, a single file is specified, and it can be read
incrementally (e.g. as it is created) by the next() method.
The nvec, nlen, and names values give the # of vectors, their length,
and names. The get() method returns one of more vectors as a Python
list. The write() method outputs the numeric vectors to a file.
[Usage:]
l = log("file1") read in one or more log files
l = log("log1 log2.gz") can be gzipped
l = log("file*") wildcard expands to multiple files
l = log("log.lammps",0) two args = store filename, but don't read :pre
incomplete and duplicate thermo entries are deleted :pre
time = l.next() read new thermo info from file :pre
used with 2-argument constructor to allow reading thermo incrementally
return time stamp of last thermo read
return -1 if no new thermo since last read :pre
nvec = l.nvec # of vectors of thermo info
nlen = l.nlen length of each vectors
names = l.names list of vector names
t,pe,... = l.get("Time","KE",...) return one or more vectors of values
l.write("file.txt") write all vectors to a file
l.write("file.txt","Time","PE",...) write listed vectors to a file :pre
get and write allow abbreviated (uniquely) vector names :pre
[Related tools:]
"clog"_clog.html, "plotview"_plotview.html, "gnu"_gnu.html,
"matlab"_matlab.html
[Prerequisites:] none

135
doc/lpp.html Normal file
View File

@ -0,0 +1,135 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<H3>lpp tool
</H3>
<P><B>Purpose:</B>
</P>
<P>This is lpp (liggghts post processing), an update to pizza.py offering better visualization
of granular (DEM) LIGGGHTS or LAMMPS simulations using pizza.py via VTK files
</P>
<HR>
<P><B>Description:</B>
</P>
<P>This update provides the possibilty to convert LIGGGHTS/LAMMPS dump files to VTK exporting:
</P>
<LI>particle radius,
<LI>particle velocity and rotational velocity vector,
<LI>particle force and torque vector,
<LI>customized vectors (e.g. calculated by a fix, compute or variable)
<LI>customized scalars (e.g. calculated by a fix, compute or variable)
<P>where the names are automatically assigned.
</P>
<P>The lpp tool runs in parallel (shared-memory) using the python "multiprocessing" tool. The number of processors can be controlled via command line args (see below).
</P>
<P>Additionally, the simulation box is also exported into VTK format
and stored in an "*_boundingBox.vtk" file
</P>
<HR>
<P><B>Prerequisites for Usage:</B>
</P>
<P>To be able to use the lpp tool, please use a dump custom command like the
following in your LIGGGHTS/LAMMPS input script:
</P>
<PRE>dump d0 all custom 100 dump*.example id type x y z ix iy iz vx vy vz fx fy fz
omegax omegay omegaz radius (customScalars) (customVectors)
</PRE>
<P>It is mandatory to use "x y z" in the dump custom command. The dump file
generated by LIGGGHTS/LAMMPS will look like this:
</P>
<PRE>ITEM: TIMESTEP
5000
ITEM: NUMBER OF ATOMS
2988
ITEM: BOX BOUNDS
-0.05 0.05
-0.05 0.05
0 0.6
ITEM: ATOMS id type x y z vx vy vz fx fy fz omegax omegay omegaz radius
</PRE>
<P>The last line contains the name strings for the per-atom quanitites.
If the syntax of a name string triple of names meets one of the following
specifications this triple is recognized as a vector:
</P>
<LI>f_vectorname[i] f_vectorname[i+1] f_vectorname[i+2]
<LI>c_vectorname[i] c_vectorname[i+1] c_vectorname[i+2]
<LI>v_vectorname[i] v_vectorname[i+1] v_vectorname[i+2]
<LI>vectornamex vectornamey vectornamez
<P>"vectorname" can be any name (e.g. "v" for velocity, "tq" for torque,
etc., a fix or compute id, or a per-atom variable name.)
</P>
<P>All other quantities are recognized as scalars.
</P>
<HR>
<P><B>Usage:</B>
</P>
<P>After the simulation is finished, type "lpp dump.mySimulation" where "dump.mySimulation"
has to be replaced the name of your dump file or type "lpp dump*.mySimulation"
</P>
<P>For more command line options, see below.
</P>
<P>Now open paraview (www.paraview.org) and import the VTK files. To display the
particles correctly, you should first create a glyph by clicking on the "glyph"
button and then in the object inspector:
</P>
<LI>Choose Scalars -->"radius"
<LI>Glyph type -->"Sphere"
<LI>Radius -->"1"
<LI>Scale mode -->"Scalar"
<LI>Set Scale Factor -->"1"
<P>In a similar fashion, you can set up vector glyphs to visualize velocity etc.
</P>
<HR>
<P><B>Command Line Options:</B>
</P>
<P>A few command line options are avaliable to control lpp:
</P>
<P>-o fname : define output file names (default is liggghts + timestep number). This option can also be used to write to a specified folder, eg. "lpp -o foo/bar dump*" will create files bar1000.vtk, bar2000.vtk etc. in the directory ./foo while "lpp -o foo/ dump*" will create files named liggghts1000.vtk, ligggghts2000.vtk etc. in ./foo (providing the directory exists, lpp will not create any directories for you!)
</P>
<P>--chunksize : sets the amount of dumpfiles processed per chunk, the default is 8. Increasing the chunksize can improve performance, but the chunksize is limited by the amount of RAM on your system. Also keep in mind that multiple chunks may be processed depending on your --cpunum settings, and thus RAM demand is multiplied.
</P>
<P>--cpunum : sets the number of processes to start, default (and maximum) is the amount of cpu cores avaliable at your system.
</P>
<P>--debug : prints debug information, usually not needed
</P>
<P>--quiet : suppresses all output but error messages (also discards --debug)
</P>
<P>--help : writes a help message and exits
</P>
<HR>
<P><B>Related tools:</B>
</P>
<P><A HREF = "vtk.html">vtk</A>, <A HREF = "dump.html">dump</A>,
</P>
<HR>
<P><B>Prerequisites:</B>
</P>
<P>Python "multiprocessing" tool
</P>
</HTML>

119
doc/lpp.txt Normal file
View File

@ -0,0 +1,119 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
lpp tool :h3
[Purpose:]
This is lpp (liggghts post processing), an update to pizza.py offering better visualization
of granular (DEM) LIGGGHTS or LAMMPS simulations using pizza.py via VTK files
:line
[Description:]
This update provides the possibilty to convert LIGGGHTS/LAMMPS dump files to VTK exporting:
particle radius, :l
particle velocity and rotational velocity vector, :l
particle force and torque vector, :l
customized vectors (e.g. calculated by a fix, compute or variable) :l
customized scalars (e.g. calculated by a fix, compute or variable) :l
where the names are automatically assigned.
The lpp tool runs in parallel (shared-memory) using the python "multiprocessing" tool. The number of processors can be controlled via command line args (see below).
Additionally, the simulation box is also exported into VTK format
and stored in an "*_boundingBox.vtk" file
:line
[Prerequisites for Usage:]
To be able to use the lpp tool, please use a dump custom command like the
following in your LIGGGHTS/LAMMPS input script:
dump d0 all custom 100 dump*.example id type x y z ix iy iz vx vy vz fx fy fz
omegax omegay omegaz radius (customScalars) (customVectors) :pre
It is mandatory to use "x y z" in the dump custom command. The dump file
generated by LIGGGHTS/LAMMPS will look like this:
ITEM: TIMESTEP
5000
ITEM: NUMBER OF ATOMS
2988
ITEM: BOX BOUNDS
-0.05 0.05
-0.05 0.05
0 0.6
ITEM: ATOMS id type x y z vx vy vz fx fy fz omegax omegay omegaz radius :pre
The last line contains the name strings for the per-atom quanitites.
If the syntax of a name string triple of names meets one of the following
specifications this triple is recognized as a vector:
f_vectorname\[i\] f_vectorname\[i+1\] f_vectorname\[i+2\] :l
c_vectorname\[i\] c_vectorname\[i+1\] c_vectorname\[i+2\] :l
v_vectorname\[i\] v_vectorname\[i+1\] v_vectorname\[i+2\] :l
vectornamex vectornamey vectornamez :l
"vectorname" can be any name (e.g. "v" for velocity, "tq" for torque,
etc., a fix or compute id, or a per-atom variable name.)
All other quantities are recognized as scalars.
:line
[Usage:]
After the simulation is finished, type "lpp dump.mySimulation" where "dump.mySimulation"
has to be replaced the name of your dump file or type "lpp dump*.mySimulation"
For more command line options, see below.
Now open paraview (www.paraview.org) and import the VTK files. To display the
particles correctly, you should first create a glyph by clicking on the "glyph"
button and then in the object inspector:
Choose Scalars -->"radius" :l
Glyph type -->"Sphere" :l
Radius -->"1" :l
Scale mode -->"Scalar" :l
Set Scale Factor -->"1" :l
In a similar fashion, you can set up vector glyphs to visualize velocity etc.
:line
[Command Line Options:]
A few command line options are avaliable to control lpp:
-o fname : define output file names (default is liggghts + timestep number). This option can also be used to write to a specified folder, eg. "lpp -o foo/bar dump*" will create files bar1000.vtk, bar2000.vtk etc. in the directory ./foo while "lpp -o foo/ dump*" will create files named liggghts1000.vtk, ligggghts2000.vtk etc. in ./foo (providing the directory exists, lpp will not create any directories for you!)
--chunksize : sets the amount of dumpfiles processed per chunk, the default is 8. Increasing the chunksize can improve performance, but the chunksize is limited by the amount of RAM on your system. Also keep in mind that multiple chunks may be processed depending on your --cpunum settings, and thus RAM demand is multiplied.
--cpunum : sets the number of processes to start, default (and maximum) is the amount of cpu cores avaliable at your system.
--debug : prints debug information, usually not needed
--quiet : suppresses all output but error messages (also discards --debug)
--help : writes a help message and exits
:line
[Related tools:]
"vtk"_vtk.html, "dump"_dump.html,
:line
[Prerequisites:]
Python "multiprocessing" tool

128
doc/matlab.html Normal file
View File

@ -0,0 +1,128 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>matlab tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Create plots via MatLab numerical analysis program.
</P>
<P><B>Description:</B>
</P>
<P>The matlab tool is a wrapper on the <A HREF = "http://www.mathworks.com">MatLab</A>
numerical analysis package, primarily designed to use its plotting
capabilities. MatLab is commercial software available on a variety
of platforms.
</P>
<P>The matlab constructor launches MatLab as a process which the matlab
tool sends commands to. The MatLab process can be killed via the
stop() method, though this is typically unnecessary.
</P>
<P>The plot() method plots a single vector against a linear index or
pairs of vectors against each other. The pairs of vectors are written
to files and read-in by MatLab. The Nth curve in a plot is stored in
the MatLab variable pizzaN, so the 2 vectors can be accessed within
MatLab as pizzaN(:,1) and pizzaN(:,2).
</P>
<P>The mplot() method creates a series of plots and saves them each to a
numbered file. Each file is a plot of an increasing portion of the
vector(s). This can be used to make an animation of a plot.
</P>
<P>The enter() method can be used to interact with MatLab directly.
Each subsequent line you type is a MatLab command, until you type
"quit" or "exit" to return to Pizza.py. Single MatLab commands can
be issued as string arguments to the gnu tool.
</P>
<P>The export() method writes numeric data as columns to text files, so
that MatLab can read them via its "importdata" command.
</P>
<P>Mutliple windows can be displayed, plotted to, and manipulated using
the select() and hide() methods. The save() method writes the
currently selected plot to a PostScript file.
</P>
<P>The remaining methods (aspect, title, xrange, etc) set attributes of
the currently selected plot. The erase() method resets all attributes
to their default values.
</P>
<P><B>Usage:</B>
</P>
<PRE>m = matlab() start up MatLab
m.stop() shut down MatLab process
</PRE>
<PRE>m.plot(a) plot vector A against linear index
m.plot(a,b) plot B against A
m.plot(a,b,c,d,...) plot B against A, D against C, etc
m.mplot(M,N,S,"file",a,b,...) multiple plots saved to file0000.eps, etc
</PRE>
<PRE> each plot argument can be a tuple, list, or Numeric/NumPy vector
mplot loops over range(M,N,S) and create one plot per iteration
last args are same as list of vectors for plot(), e.g. 1, 2, 4 vectors
each plot is made from a portion of the vectors, depending on loop index i
Ith plot is of b[0:i] vs a[0:i], etc
series of plots saved as file0000.eps, file0001.eps, etc
if use xrange(),yrange() then plot axes will be same for all plots
</PRE>
<PRE>m("c = a + b") execute string in MatLab
</PRE>
<PRE>m.enter() enter MatLab shell
matlab> c = a + b type commands directly to MatLab
matlab> exit, quit exit MatLab shell
</PRE>
<PRE>m.export("data",range(100),a,...) create file with columns of numbers
</PRE>
<PRE> all vectors must be of equal length
could plot from file with MatLab commands:
cols = importdata('data')
plot(cols(:,1),cols(:,2))
</PRE>
<PRE>m.select(N) figure N becomes the current plot
</PRE>
<PRE> subsequent commands apply to this plot
</PRE>
<PRE>m.hide(N) delete window for figure N
m.save("file") save current plot as file.eps
</PRE>
<PRE>Set attributes for current plot:
</PRE>
<PRE>m.erase() reset all attributes to default values
m.aspect(1.3) aspect ratio
m.xtitle("Time") x axis text
m.ytitle("Energy") y axis text
m.title("My Plot") title text
m.title("title","x","y") title, x axis, y axis text
m.xrange(xmin,xmax) x axis range
m.xrange() default x axis range
m.yrange(ymin,ymax) y axis range
m.yrange() default y axis range
m.xlog() toggle x axis between linear and log
m.ylog() toggle y axis between linear and log
m.label(x,y,"text") place label at x,y coords
m.curve(N,'r') set color of curve N
m.curve(N,'g','--') set color and line style of curve N
m.curve(N,'b','-','v') set color, line style, symbol of curve N
</PRE>
<PRE> colors: 'k' = black, 'r' = red, 'g' = green, 'b' = blue
'm' = magenta, 'c' = cyan, 'y' = yellow
styles: '-' = solid, '--' = dashed, ':' = dotted, '-.' = dash-dot
symbols: '+' = plus, 'o' = circle, '*' = asterik, 'x' = X,
's' = square, 'd' = diamond, '^' = up triangle,
'v' = down triangle, '>' = right triangle,
'<' = left triangle, 'p' = pentagram, 'h' = hexagram
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "gnu.html">gnu</A>, <A HREF = "plotview.html">plotview</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>The MatLab numerical analysis package.
</P>
</HTML>

123
doc/matlab.txt Normal file
View File

@ -0,0 +1,123 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
matlab tool :h3
[Purpose:]
Create plots via MatLab numerical analysis program.
[Description:]
The matlab tool is a wrapper on the "MatLab"_http://www.mathworks.com
numerical analysis package, primarily designed to use its plotting
capabilities. MatLab is commercial software available on a variety
of platforms.
The matlab constructor launches MatLab as a process which the matlab
tool sends commands to. The MatLab process can be killed via the
stop() method, though this is typically unnecessary.
The plot() method plots a single vector against a linear index or
pairs of vectors against each other. The pairs of vectors are written
to files and read-in by MatLab. The Nth curve in a plot is stored in
the MatLab variable pizzaN, so the 2 vectors can be accessed within
MatLab as pizzaN(:,1) and pizzaN(:,2).
The mplot() method creates a series of plots and saves them each to a
numbered file. Each file is a plot of an increasing portion of the
vector(s). This can be used to make an animation of a plot.
The enter() method can be used to interact with MatLab directly.
Each subsequent line you type is a MatLab command, until you type
"quit" or "exit" to return to Pizza.py. Single MatLab commands can
be issued as string arguments to the gnu tool.
The export() method writes numeric data as columns to text files, so
that MatLab can read them via its "importdata" command.
Mutliple windows can be displayed, plotted to, and manipulated using
the select() and hide() methods. The save() method writes the
currently selected plot to a PostScript file.
The remaining methods (aspect, title, xrange, etc) set attributes of
the currently selected plot. The erase() method resets all attributes
to their default values.
[Usage:]
m = matlab() start up MatLab
m.stop() shut down MatLab process :pre
m.plot(a) plot vector A against linear index
m.plot(a,b) plot B against A
m.plot(a,b,c,d,...) plot B against A, D against C, etc
m.mplot(M,N,S,"file",a,b,...) multiple plots saved to file0000.eps, etc :pre
each plot argument can be a tuple, list, or Numeric/NumPy vector
mplot loops over range(M,N,S) and create one plot per iteration
last args are same as list of vectors for plot(), e.g. 1, 2, 4 vectors
each plot is made from a portion of the vectors, depending on loop index i
Ith plot is of b\[0:i\] vs a\[0:i\], etc
series of plots saved as file0000.eps, file0001.eps, etc
if use xrange(),yrange() then plot axes will be same for all plots :pre
m("c = a + b") execute string in MatLab :pre
m.enter() enter MatLab shell
matlab> c = a + b type commands directly to MatLab
matlab> exit, quit exit MatLab shell :pre
m.export("data",range(100),a,...) create file with columns of numbers :pre
all vectors must be of equal length
could plot from file with MatLab commands:
cols = importdata('data')
plot(cols(:,1),cols(:,2)) :pre
m.select(N) figure N becomes the current plot :pre
subsequent commands apply to this plot :pre
m.hide(N) delete window for figure N
m.save("file") save current plot as file.eps :pre
Set attributes for current plot: :pre
m.erase() reset all attributes to default values
m.aspect(1.3) aspect ratio
m.xtitle("Time") x axis text
m.ytitle("Energy") y axis text
m.title("My Plot") title text
m.title("title","x","y") title, x axis, y axis text
m.xrange(xmin,xmax) x axis range
m.xrange() default x axis range
m.yrange(ymin,ymax) y axis range
m.yrange() default y axis range
m.xlog() toggle x axis between linear and log
m.ylog() toggle y axis between linear and log
m.label(x,y,"text") place label at x,y coords
m.curve(N,'r') set color of curve N
m.curve(N,'g','--') set color and line style of curve N
m.curve(N,'b','-','v') set color, line style, symbol of curve N :pre
colors: 'k' = black, 'r' = red, 'g' = green, 'b' = blue
'm' = magenta, 'c' = cyan, 'y' = yellow
styles: '-' = solid, '--' = dashed, ':' = dotted, '-.' = dash-dot
symbols: '+' = plus, 'o' = circle, '*' = asterik, 'x' = X,
's' = square, 'd' = diamond, '^' = up triangle,
'v' = down triangle, '>' = right triangle,
'<' = left triangle, 'p' = pentagram, 'h' = hexagram :pre
[Related tools:]
"gnu"_gnu.html, "plotview"_plotview.html
[Prerequisites:]
The MatLab numerical analysis package.

287
doc/mdump.html Normal file
View File

@ -0,0 +1,287 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>mdump tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read, write, manipulate mesh dump files.
</P>
<P><B>Description:</B>
</P>
<P>The mdump tool reads one or more mesh dump files, stores their
contents as a series of snapshots with node and element values, and
allows the values to be accessed and manipulated. Other tools use
mdump objects to convert mesh files to other formats or visualize the
mesh.
</P>
<P>The constructor method is passed a string containing one or more mesh
dump filenames. They can be listed in any order since snapshots are
sorted by timestep after they are read and duplicate snapshots (with
the same time stamp) are deleted. If a 2nd argument is specified, the
files are not immediately read, but snapshots can be read
one-at-a-time by the next() method.
</P>
<P>The map() method assigns names to columns of element values. The
tselect() methods select one or more snapshots by their time stamp.
The delete() method deletes unselected timesteps so their memory is
freed up. This can be useful to do when reading snapshots
one-at-a-time for huge data sets. The eselect() methods selects
elements within selected snapshots.
</P>
<P>The time() and vecs() methods return time or element values as vectors
of values.
</P>
<P>The iterator() and viz() methods are called by Pizza.py tools that
visualize triangles (e.g. gl, raster, svg tools). You can also use
the iterator() method in your scripts to loop over selected snapshots.
The etype setting determines what element value is returned as the
element "type" by the viz() method. The mviz() method is called by
the ensight tool to extract per-node and per-element data to include
in Ensight files it outputs, so that it can visualized in the Ensight
package.
</P>
<HR>
<P>The format of mesh dump files read in by this tool is simple. There
are 4 kinds of entries that can appear within each timestep, in any
order. These are a list of node coordinates, a list of element
topologies (trianglular, tetrahedral, square, and cubic elements are
currently supported), a list of nodal values, and a list of element
values. Note that a mesh file does not need to include all 4 entries
every timestep. For example, if the file only defines a mesh, but no
nodal or element values, then those two entries need not appear. If
the mesh is static, then the nodal coordinates and element topologies
only need to be defined once (e.g. for timestep 0). If the mesh
moves, but its topology is static, then the element topology will be
defined once (timestep 0), but new nodal coordinates could be defined
every timestamp.
</P>
<P>A single mesh file can contain multiple snapshots, listed one after
the other.
</P>
<P>The format of a nodal coordinates entry is as follows:
</P>
<PRE>ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
121
ITEM: BOX BOUNDS
0 10
0 10
0 0
ITEM: NODES
1 1 0 0 0
2 1 0 1 0
3 1 0 2 0
...
N 3 7.5 3 2.5
</PRE>
<P>The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
NODES" where N is the number of nodes. The nodes do not need to be
listed in any particular order. There can be a different number of
nodes in each snapshot. The values on each node line are "ID type x y
z".
</P>
<P>The format of an element topology entry is in one of the following
styles (triangles, tetrahedra, squares, cubes):
</P>
<PRE>ITEM: TIMESTEP
0
ITEM: NUMBER OF TRIANGLES
200
ITEM: TRIANGLES
1 1 1 13 12
2 1 1 2 13
3 1 2 14 13
...
N 3 259 340 432
</PRE>
<PRE>ITEM: TIMESTEP
0
ITEM: NUMBER OF TETS
200
ITEM: TETS
1 1 1 13 12 27
2 1 1 2 13 35
3 1 2 14 13 103
...
N 3 259 340 432 1005
</PRE>
<PRE>ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
200
ITEM: SQUARES
1 1 1 13 12 4
2 1 1 2 13 6
3 1 2 14 13 11
...
N 3 259 340 432 500
</PRE>
<PRE>ITEM: TIMESTEP
0
ITEM: NUMBER OF CUBES
200
ITEM: CUBES
1 1 1 13 12 5 3 6 10 20
2 1 1 2 13 10 3 4 5 6
3 1 2 14 13 15 10 18 19
...
N 3 259 340 432 200 456 918 1002 988
</PRE>
<P>There are N lines following "ITEM: TRIANGLES" or "ITEM: TETS" or
"ITEM: SQUARES" or "ITEM: CUBES" where N is the number of elements.
The elements do not need to be listed in any particular order. There
can be a different number of elements in each snapshot. The values on
each element line are "ID type node1 node2 ... nodeN", where N depends
on the type of element. For triangles, N = 3, and the order should
give an outward normal via the right-hand rule. For tets, N = 4, and
the order should give a right-hand rule for the first 3 nodes that
points towards the 4th node. For squares, N = 4, and the nodes should
be listed in counter-clockwise order around the square. For cubes, N
= 8, and the first 4 nodes are the lower face (ordered same as a
square), and the last 4 nodes are directly above the lower 4 as the
upper face.
</P>
<P>The format of a nodal values entry is as follows:
</P>
<PRE>ITEM: TIMESTEP
0
ITEM: NUMBER OF NODE VALUES
200
ITEM: NODE VALUES
1 1
2 1
3 9
...
N 32
</PRE>
<P>There are N lines following "ITEM: NODE VALUES" where N is the number
of nodes. The nodes do not need to be listed in any particular order.
There can be a different number of nodes in each snapshot, but it
should be consistent with the current nodal coordinates entry. The
values on each node line are "ID value1 value2 ..." where there are
as many columns as desired. Each line should have the same number of
values.
</P>
<P>The format of an element values entry is as follows:
</P>
<PRE>ITEM: TIMESTEP
0
ITEM: NUMBER OF ELEMENT VALUES
200
ITEM: ELEMENT VALUES
1 1
2 1
3 9
...
N 32
</PRE>
<P>There are N lines following "ITEM: ELEMENT VALUES" where N is the
number of elements. The elements do not need to be listed in any
particular order. There can be a different number of elements in each
snapshot, but it should be consistent with the current element
topology entry. The values on each element line are "ID value1 value2
..." where there are as many columns as desired. Each line should
have the same number of values. The map() command can be used to
assign names to each of these columns of values.
</P>
<HR>
<P><B>Usage:</B>
</P>
<PRE>m = mdump("mesh.one") read in one or more mesh dump files
m = mdump("mesh.1 mesh.2.gz") can be gzipped
m = mdump("mesh.*") wildcard expands to multiple files
m = mdump("mesh.*",0) two args = store filenames, but don't read
</PRE>
<PRE> incomplete and duplicate snapshots are deleted
</PRE>
<PRE>time = m.next() read next snapshot from dump files
</PRE>
<PRE> used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment or unscaling is performed
</PRE>
<PRE>m.map(2,"temperature") assign names to element value columns (1-N)
</PRE>
<PRE>m.tselect.all() select all timesteps
m.tselect.one(N) select only timestep N
m.tselect.none() deselect all timesteps
m.tselect.skip(M) select every Mth step
m.tselect.test("$t >= 100 and $t < 10000") select matching timesteps
m.delete() delete non-selected timesteps
</PRE>
<PRE> selecting a timestep also selects all elements in the timestep
skip() and test() only select from currently selected timesteps
test() uses a Python Boolean expression with $t for timestep value
Python comparison syntax: == != < > <= >= and or
</PRE>
<PRE>m.eselect.all() select all elems in all steps
m.eselect.all(N) select all elems in one step
m.eselect.test("$id > 100 and $type == 2") select match elems in all steps
m.eselect.test("$id > 100 and $type == 2",N) select matching elems in one step
</PRE>
<PRE> all() with no args selects atoms from currently selected timesteps
test() with one arg selects atoms from currently selected timesteps
test() sub-selects from currently selected elements
test() uses a Python Boolean expression with $ for atom attributes
Python comparison syntax: == != < > <= >= and or
$name must end with a space
</PRE>
<PRE>t = m.time() return vector of selected timestep values
fx,fy,... = m.vecs(1000,"fx","fy",...) return vector(s) for timestep N
</PRE>
<PRE> vecs() returns vectors with one value for each selected elem in the timestep
</PRE>
<PRE>index,time,flag = m.iterator(0/1) loop over mesh dump snapshots
time,box,atoms,bonds,tris,lines = m.viz(index) return list of viz objects
nodes,elements,nvalues,evalues = m.mviz(index) return list of mesh viz objects
m.etype = "color" set column returned as "type" by viz
</PRE>
<PRE> iterator() loops over selected timesteps
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = index within dump object (0 to # of snapshots)
time = timestep value
flag = -1 when iteration is done, 1 otherwise
viz() returns info for selected elements for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
atoms = NULL
bonds = NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
each element is decomposed into tris
lines = NULL
mviz() returns info for all elements for specified timestep index
can also call as mviz(time,1) and will find index of preceding snapshot
time = timestep value
box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
nodes = list of nodes = id,type,x,y,z
elements = list of elements = id,type,node1,node2,...
nvalues = list of node values = id,type,value1,value2,...
evalues = list of element values = id,type,value1,value2,...
etype is column name viz() will return as element type (def = "" = elem type)
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "gl.html">gl</A>, <A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).
</P>
</HTML>

282
doc/mdump.txt Normal file
View File

@ -0,0 +1,282 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
mdump tool :h3
[Purpose:]
Read, write, manipulate mesh dump files.
[Description:]
The mdump tool reads one or more mesh dump files, stores their
contents as a series of snapshots with node and element values, and
allows the values to be accessed and manipulated. Other tools use
mdump objects to convert mesh files to other formats or visualize the
mesh.
The constructor method is passed a string containing one or more mesh
dump filenames. They can be listed in any order since snapshots are
sorted by timestep after they are read and duplicate snapshots (with
the same time stamp) are deleted. If a 2nd argument is specified, the
files are not immediately read, but snapshots can be read
one-at-a-time by the next() method.
The map() method assigns names to columns of element values. The
tselect() methods select one or more snapshots by their time stamp.
The delete() method deletes unselected timesteps so their memory is
freed up. This can be useful to do when reading snapshots
one-at-a-time for huge data sets. The eselect() methods selects
elements within selected snapshots.
The time() and vecs() methods return time or element values as vectors
of values.
The iterator() and viz() methods are called by Pizza.py tools that
visualize triangles (e.g. gl, raster, svg tools). You can also use
the iterator() method in your scripts to loop over selected snapshots.
The etype setting determines what element value is returned as the
element "type" by the viz() method. The mviz() method is called by
the ensight tool to extract per-node and per-element data to include
in Ensight files it outputs, so that it can visualized in the Ensight
package.
:line
The format of mesh dump files read in by this tool is simple. There
are 4 kinds of entries that can appear within each timestep, in any
order. These are a list of node coordinates, a list of element
topologies (trianglular, tetrahedral, square, and cubic elements are
currently supported), a list of nodal values, and a list of element
values. Note that a mesh file does not need to include all 4 entries
every timestep. For example, if the file only defines a mesh, but no
nodal or element values, then those two entries need not appear. If
the mesh is static, then the nodal coordinates and element topologies
only need to be defined once (e.g. for timestep 0). If the mesh
moves, but its topology is static, then the element topology will be
defined once (timestep 0), but new nodal coordinates could be defined
every timestamp.
A single mesh file can contain multiple snapshots, listed one after
the other.
The format of a nodal coordinates entry is as follows:
ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
121
ITEM: BOX BOUNDS
0 10
0 10
0 0
ITEM: NODES
1 1 0 0 0
2 1 0 1 0
3 1 0 2 0
...
N 3 7.5 3 2.5 :pre
The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
NODES" where N is the number of nodes. The nodes do not need to be
listed in any particular order. There can be a different number of
nodes in each snapshot. The values on each node line are "ID type x y
z".
The format of an element topology entry is in one of the following
styles (triangles, tetrahedra, squares, cubes):
ITEM: TIMESTEP
0
ITEM: NUMBER OF TRIANGLES
200
ITEM: TRIANGLES
1 1 1 13 12
2 1 1 2 13
3 1 2 14 13
...
N 3 259 340 432 :pre
ITEM: TIMESTEP
0
ITEM: NUMBER OF TETS
200
ITEM: TETS
1 1 1 13 12 27
2 1 1 2 13 35
3 1 2 14 13 103
...
N 3 259 340 432 1005 :pre
ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
200
ITEM: SQUARES
1 1 1 13 12 4
2 1 1 2 13 6
3 1 2 14 13 11
...
N 3 259 340 432 500 :pre
ITEM: TIMESTEP
0
ITEM: NUMBER OF CUBES
200
ITEM: CUBES
1 1 1 13 12 5 3 6 10 20
2 1 1 2 13 10 3 4 5 6
3 1 2 14 13 15 10 18 19
...
N 3 259 340 432 200 456 918 1002 988 :pre
There are N lines following "ITEM: TRIANGLES" or "ITEM: TETS" or
"ITEM: SQUARES" or "ITEM: CUBES" where N is the number of elements.
The elements do not need to be listed in any particular order. There
can be a different number of elements in each snapshot. The values on
each element line are "ID type node1 node2 ... nodeN", where N depends
on the type of element. For triangles, N = 3, and the order should
give an outward normal via the right-hand rule. For tets, N = 4, and
the order should give a right-hand rule for the first 3 nodes that
points towards the 4th node. For squares, N = 4, and the nodes should
be listed in counter-clockwise order around the square. For cubes, N
= 8, and the first 4 nodes are the lower face (ordered same as a
square), and the last 4 nodes are directly above the lower 4 as the
upper face.
The format of a nodal values entry is as follows:
ITEM: TIMESTEP
0
ITEM: NUMBER OF NODE VALUES
200
ITEM: NODE VALUES
1 1
2 1
3 9
...
N 32 :pre
There are N lines following "ITEM: NODE VALUES" where N is the number
of nodes. The nodes do not need to be listed in any particular order.
There can be a different number of nodes in each snapshot, but it
should be consistent with the current nodal coordinates entry. The
values on each node line are "ID value1 value2 ..." where there are
as many columns as desired. Each line should have the same number of
values.
The format of an element values entry is as follows:
ITEM: TIMESTEP
0
ITEM: NUMBER OF ELEMENT VALUES
200
ITEM: ELEMENT VALUES
1 1
2 1
3 9
...
N 32 :pre
There are N lines following "ITEM: ELEMENT VALUES" where N is the
number of elements. The elements do not need to be listed in any
particular order. There can be a different number of elements in each
snapshot, but it should be consistent with the current element
topology entry. The values on each element line are "ID value1 value2
..." where there are as many columns as desired. Each line should
have the same number of values. The map() command can be used to
assign names to each of these columns of values.
:line
[Usage:]
m = mdump("mesh.one") read in one or more mesh dump files
m = mdump("mesh.1 mesh.2.gz") can be gzipped
m = mdump("mesh.*") wildcard expands to multiple files
m = mdump("mesh.*",0) two args = store filenames, but don't read :pre
incomplete and duplicate snapshots are deleted :pre
time = m.next() read next snapshot from dump files :pre
used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment or unscaling is performed :pre
m.map(2,"temperature") assign names to element value columns (1-N) :pre
m.tselect.all() select all timesteps
m.tselect.one(N) select only timestep N
m.tselect.none() deselect all timesteps
m.tselect.skip(M) select every Mth step
m.tselect.test("$t >= 100 and $t < 10000") select matching timesteps
m.delete() delete non-selected timesteps :pre
selecting a timestep also selects all elements in the timestep
skip() and test() only select from currently selected timesteps
test() uses a Python Boolean expression with $t for timestep value
Python comparison syntax: == != < > <= >= and or :pre
m.eselect.all() select all elems in all steps
m.eselect.all(N) select all elems in one step
m.eselect.test("$id > 100 and $type == 2") select match elems in all steps
m.eselect.test("$id > 100 and $type == 2",N) select matching elems in one step :pre
all() with no args selects atoms from currently selected timesteps
test() with one arg selects atoms from currently selected timesteps
test() sub-selects from currently selected elements
test() uses a Python Boolean expression with $ for atom attributes
Python comparison syntax: == != < > <= >= and or
$name must end with a space :pre
t = m.time() return vector of selected timestep values
fx,fy,... = m.vecs(1000,"fx","fy",...) return vector(s) for timestep N :pre
vecs() returns vectors with one value for each selected elem in the timestep :pre
index,time,flag = m.iterator(0/1) loop over mesh dump snapshots
time,box,atoms,bonds,tris,lines = m.viz(index) return list of viz objects
nodes,elements,nvalues,evalues = m.mviz(index) return list of mesh viz objects
m.etype = "color" set column returned as "type" by viz :pre
iterator() loops over selected timesteps
iterator() called with arg = 0 first time, with arg = 1 on subsequent calls
index = index within dump object (0 to # of snapshots)
time = timestep value
flag = -1 when iteration is done, 1 otherwise
viz() returns info for selected elements for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \\[xlo,ylo,zlo,xhi,yhi,zhi\\]
atoms = NULL
bonds = NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3,nx,ny,nz for each tri as 2d array
each element is decomposed into tris
lines = NULL
mviz() returns info for all elements for specified timestep index
can also call as mviz(time,1) and will find index of preceding snapshot
time = timestep value
box = \\[xlo,ylo,zlo,xhi,yhi,zhi\\]
nodes = list of nodes = id,type,x,y,z
elements = list of elements = id,type,node1,node2,...
nvalues = list of node values = id,type,value1,value2,...
evalues = list of element values = id,type,value1,value2,...
etype is column name viz() will return as element type (def = "" = elem type) :pre
[Related tools:]
"dump"_dump.html, "gl"_gl.html, "raster"_raster.html, "svg"_svg.html
[Prerequisites:]
Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).

68
doc/pair.html Normal file
View File

@ -0,0 +1,68 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>pair tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Compute LAMMPS pairwise energies.
</P>
<P><B>Description:</B>
</P>
<P>The pair tool computes a pairwise energy between 2 particles using a
LAMMPS molecular dynamics force field. Thus it can be used in an
analysis script to compute energies between groups of atoms from a
LAMMPS snapshot file.
</P>
<P>The pair constructor specifies the force field style. Only some of
the LAMMPS pair styles are currently included in this tool, but new
styles can easily be added. Code from the LAMMPS pair*.cpp file needs
to be re-coded in Python to make this work.
</P>
<P>The coeff() method reads the pairwise coefficients for the force field
from a data file object (see the <A HREF = "data.html">data</A> tool). The init()
method does pre-computations for the force field parameters needed by
the single() method which does a pairwise computation between two
atoms of type = itype,jtype separated by a squared distance rsq. The
arguments for init() and single() can be different for a particular
force field style. When you write the init() and single() methods for
a new style, you can define what arguments are needed.
</P>
<P><B>Usage:</B>
</P>
<PRE>p = pair("lj/charmm/coul/charmm") create pair object for specific pair style
</PRE>
<PRE> available styles: lj/cut, lj/cut/coul/cut, lj/charmm/coul/charmm
</PRE>
<PRE>p.coeff(d) extract pairwise coeffs from data object
p.init(cut1,cut2,...) setup based on coeffs and cutoffs
</PRE>
<PRE> init args are specific to pair style:
lj/cut = cutlj
lj/cut/coul/cut = cutlj,cut_coul (cut_coul optional)
lj/charmm/coul/charmm = cutlj_inner,cutlj,cutcoul_inner,cut_coul
(last 2 optional)
</PRE>
<PRE>e_vdwl,e_coul = p.single(rsq,itype,jtype,q1,q2,...) compute LJ/Coul energy
</PRE>
<PRE> pairwise energy between 2 atoms at distance rsq with their attributes
args are specific to pair style:
lj/cut = rsq,itype,jtype
lj/cut/coul/cut = rsq,itype,jtype,q1,q2
lj/charmm/coul/charmm = rsq,itype,jtype,q1,q2
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "data.html">data</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

63
doc/pair.txt Normal file
View File

@ -0,0 +1,63 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
pair tool :h3
[Purpose:]
Compute LAMMPS pairwise energies.
[Description:]
The pair tool computes a pairwise energy between 2 particles using a
LAMMPS molecular dynamics force field. Thus it can be used in an
analysis script to compute energies between groups of atoms from a
LAMMPS snapshot file.
The pair constructor specifies the force field style. Only some of
the LAMMPS pair styles are currently included in this tool, but new
styles can easily be added. Code from the LAMMPS pair*.cpp file needs
to be re-coded in Python to make this work.
The coeff() method reads the pairwise coefficients for the force field
from a data file object (see the "data"_data.html tool). The init()
method does pre-computations for the force field parameters needed by
the single() method which does a pairwise computation between two
atoms of type = itype,jtype separated by a squared distance rsq. The
arguments for init() and single() can be different for a particular
force field style. When you write the init() and single() methods for
a new style, you can define what arguments are needed.
[Usage:]
p = pair("lj/charmm/coul/charmm") create pair object for specific pair style :pre
available styles: lj/cut, lj/cut/coul/cut, lj/charmm/coul/charmm :pre
p.coeff(d) extract pairwise coeffs from data object
p.init(cut1,cut2,...) setup based on coeffs and cutoffs :pre
init args are specific to pair style:
lj/cut = cutlj
lj/cut/coul/cut = cutlj,cut_coul (cut_coul optional)
lj/charmm/coul/charmm = cutlj_inner,cutlj,cutcoul_inner,cut_coul
(last 2 optional) :pre
e_vdwl,e_coul = p.single(rsq,itype,jtype,q1,q2,...) compute LJ/Coul energy :pre
pairwise energy between 2 atoms at distance rsq with their attributes
args are specific to pair style:
lj/cut = rsq,itype,jtype
lj/cut/coul/cut = rsq,itype,jtype,q1,q2
lj/charmm/coul/charmm = rsq,itype,jtype,q1,q2 :pre
[Related tools:]
"data"_data.html
[Prerequisites:] none

107
doc/patch.html Normal file
View File

@ -0,0 +1,107 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>patch tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Create patchy Lennard-Jones particles for LAMMPS input.
</P>
<P><B>Description:</B>
</P>
<P>The patch tool creates large multi-atom particles and writes them out
as a LAMMPS data file. They need to be simulated with a soft
potential in LAMMPS to un-overlap them before they form a proper
ensemble.
</P>
<P>The individual particles consist of a collection of Lennard-Jones
atoms of various types. By defining force field coefficients
appropriately, specific atoms can be made attractive or repulsive, so
that "patches" of atoms on the particle surface are reactive. The
<A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW site</A> has example images and movies of simulations
using such particles. A <A HREF = "#Glotzer">paper</A> by <A HREF = "http://www.engin.umich.edu/dept/che/research/glotzer">Sharon Glotzer's
group</A> at U Michigan describing a variety of patchy particle
models was the motivation for this tool.
</P>
<P>The patch constructor takes a volume fraction as an argument to determine
how densely to fill the simulation box. Optionally, the box shape can
also be specified.
</P>
<P>The build() method creates N particles, each of speficied style and
with specified atom types. Several styles are available and new ones
can easily be added to patch.py. You will need to look in patch.py
for the details of what each style represents. For example, "hex2"
uses a C60 bucky ball as a template and creates hexagonal 6-atom
patches (atoms of a different type) on either side of the ball.
</P>
<P>The build() method can be invoked multiple times to create collections
of particles. The position and orientation of each particle is chosen
randomly. The seed value sets the random number generator used for
coordinate generation.
</P>
<P>The ensemble of chains is written to a LAMMPS data file via the
write() method.
</P>
<P><B>Usage:</B>
</P>
<PRE>p = patch(vfrac) setup box with a specified volume fraction
p = patch(vfrac,1,1,2) x,y,z = aspect ratio of box (def = 1,1,1)
</PRE>
<PRE>p.seed = 48379 set random # seed (def = 12345)
p.randomized = 0 1 = choose next particle randomly, 0 = as generated
p.dim = 2 set dimension of created box (def = 3)
p.blen = 0.97 set length of tether bonds (def = 0.97)
p.dmin = 1.02 set min r from i-1 to i+1 tether site (def = 1.02)
p.lattice = [Nx,Ny,Nz] generate Nx by Ny by Nz lattice of particles
</PRE>
<PRE> if lattice is set, Nx*Ny*Nz must equal N for build
lattice = [0,0,0] = generate N particles randomly, default
</PRE>
<PRE>p.build(100,"hex2",1,2,3) create 100 "hex2" particles with types 1,2,3
</PRE>
<PRE> can be invoked multiple times
keywords:
c60hex2: diam,1,2,3 = C-60 with 2 hex patches and ctr part, types 1,2,3
hex2: diam,1,2 = one large particle with 2 7-mer hex patches, types 1,2
hex4: diam,1,2 = one large particle with 4 7-mer hex patches, types 1,2
ring: diam,N,1,2 = one large part with equatorial ring of N, types 1,2
ball: diam,m1,m2,1,2,3 = large ball with m12-len tethers, types 1,2,3
tri5: 1,2 = 3-layer 5-size hollow tri, types 1,2
rod: N,m1,m2,1,2,3 = N-length rod with m12-len tethers, types 1,2,3
tri: N,m1,m2,m3,1,2,3,4 = N-size tri with m123-len tethers, types 1-4
hex: m1,m2,m3,m4,m5,m6,1,2,3,4,5,6,7 = 7-atom hex with m-len tethers, t 1-7
dimer: r,1 = two particles r apart, type 1, no bond
star2d: N,r,1 = 2d star of length N (odd), beads r apart, type 1, no bonds
box2d: N,M,r,1 = 2d NxM box, beads r apart, type 1, no bonds
tritet: A,m = 4-tri tet with edge length A, tri type m
tribox: Alo,Ahi,Blo,Bhi,Clo,Chi,m = 12-tri box with side lengths A,B,C & m
linebox: Alo,Ahi,Blo,Bhi,m = 4-line 2d rectangle with random side lengths
from Alo to Ahi and Blo to Bhi, line type m
linetri: Alo,Ahi,Blo,Bhi,m = 3-line 2d triangle with random base
from Alo to Ahi and height Blo to Bhi, type m
</PRE>
<PRE>p.write("data.patch") write out system to LAMMPS data file
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "chain.html">chain</A>, <A HREF = "data.html">data</A>
</P>
<P><B>Prerequisites:</B> none
</P>
<HR>
<A NAME = "Glotzer"></A>
<P><B>(Glotzer)</B> Zhang and Glotzer, NanoLetters, 4, 1407-1413 (2004).
</P>
</HTML>

101
doc/patch.txt Normal file
View File

@ -0,0 +1,101 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
patch tool :h3
[Purpose:]
Create patchy Lennard-Jones particles for LAMMPS input.
[Description:]
The patch tool creates large multi-atom particles and writes them out
as a LAMMPS data file. They need to be simulated with a soft
potential in LAMMPS to un-overlap them before they form a proper
ensemble.
The individual particles consist of a collection of Lennard-Jones
atoms of various types. By defining force field coefficients
appropriately, specific atoms can be made attractive or repulsive, so
that "patches" of atoms on the particle surface are reactive. The
"Pizza.py WWW site"_pws has example images and movies of simulations
using such particles. A "paper"_#Glotzer by "Sharon Glotzer's
group"_glotzer at U Michigan describing a variety of patchy particle
models was the motivation for this tool.
:link(glotzer,http://www.engin.umich.edu/dept/che/research/glotzer)
The patch constructor takes a volume fraction as an argument to determine
how densely to fill the simulation box. Optionally, the box shape can
also be specified.
The build() method creates N particles, each of speficied style and
with specified atom types. Several styles are available and new ones
can easily be added to patch.py. You will need to look in patch.py
for the details of what each style represents. For example, "hex2"
uses a C60 bucky ball as a template and creates hexagonal 6-atom
patches (atoms of a different type) on either side of the ball.
The build() method can be invoked multiple times to create collections
of particles. The position and orientation of each particle is chosen
randomly. The seed value sets the random number generator used for
coordinate generation.
The ensemble of chains is written to a LAMMPS data file via the
write() method.
[Usage:]
p = patch(vfrac) setup box with a specified volume fraction
p = patch(vfrac,1,1,2) x,y,z = aspect ratio of box (def = 1,1,1) :pre
p.seed = 48379 set random # seed (def = 12345)
p.randomized = 0 1 = choose next particle randomly, 0 = as generated
p.dim = 2 set dimension of created box (def = 3)
p.blen = 0.97 set length of tether bonds (def = 0.97)
p.dmin = 1.02 set min r from i-1 to i+1 tether site (def = 1.02)
p.lattice = \[Nx,Ny,Nz\] generate Nx by Ny by Nz lattice of particles :pre
if lattice is set, Nx*Ny*Nz must equal N for build
lattice = \[0,0,0\] = generate N particles randomly, default :pre
p.build(100,"hex2",1,2,3) create 100 "hex2" particles with types 1,2,3 :pre
can be invoked multiple times
keywords:
c60hex2: diam,1,2,3 = C-60 with 2 hex patches and ctr part, types 1,2,3
hex2: diam,1,2 = one large particle with 2 7-mer hex patches, types 1,2
hex4: diam,1,2 = one large particle with 4 7-mer hex patches, types 1,2
ring: diam,N,1,2 = one large part with equatorial ring of N, types 1,2
ball: diam,m1,m2,1,2,3 = large ball with m12-len tethers, types 1,2,3
tri5: 1,2 = 3-layer 5-size hollow tri, types 1,2
rod: N,m1,m2,1,2,3 = N-length rod with m12-len tethers, types 1,2,3
tri: N,m1,m2,m3,1,2,3,4 = N-size tri with m123-len tethers, types 1-4
hex: m1,m2,m3,m4,m5,m6,1,2,3,4,5,6,7 = 7-atom hex with m-len tethers, t 1-7
dimer: r,1 = two particles r apart, type 1, no bond
star2d: N,r,1 = 2d star of length N (odd), beads r apart, type 1, no bonds
box2d: N,M,r,1 = 2d NxM box, beads r apart, type 1, no bonds
tritet: A,m = 4-tri tet with edge length A, tri type m
tribox: Alo,Ahi,Blo,Bhi,Clo,Chi,m = 12-tri box with side lengths A,B,C & m
linebox: Alo,Ahi,Blo,Bhi,m = 4-line 2d rectangle with random side lengths
from Alo to Ahi and Blo to Bhi, line type m
linetri: Alo,Ahi,Blo,Bhi,m = 3-line 2d triangle with random base
from Alo to Ahi and height Blo to Bhi, type m :pre
p.write("data.patch") write out system to LAMMPS data file :pre
[Related tools:]
"chain"_chain.html, "data"_data.html
[Prerequisites:] none
:line
:link(Glotzer)
[(Glotzer)] Zhang and Glotzer, NanoLetters, 4, 1407-1413 (2004).

98
doc/pdbfile.html Normal file
View File

@ -0,0 +1,98 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>pdbfile tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read, write PDB files in combo with LAMMPS snapshots.
</P>
<P><B>Description:</B>
</P>
<P>The pdbfile tool reads in PDB (Protein Data Bank) files of protein
coordinates and uses them in conjunction with LAMMPS snapshots in
various ways. The PDB format is commonly used by various
vizualization and analysis programs.
</P>
<P>The pdbfile constructor takes a string argument listing one or more
PDB filenames and a data argument with LAMMPS atom information
(<A HREF = "data.html">data</A> or <A HREF = "dump.html">dump</A> object). The atom snapshots
must have "id", "type", "x", "y", and "z" defined; see the map()
methods of those tools.
</P>
<P>Both arguments to the constructor are optional, as described below.
If a single PDB file is given as a constructor argument, and it is 4
letters long, and it does not exist on your system, then it is treated
as a PDB identifier and the matching PDB file is downloaded from a PDB
repository on the WWW to your machine.
</P>
<P>The one(), many(), and single() methods write out PDB files in various
manners, depending on the 1 or 2 arguments used in the constructor.
If only a string was specified (no data object), the specified PDB
files are written out as-is. Thus the one() method concatenates the
files together. If only a data object was specified (no string of PDB
files), then PDB files in a generic format (Lennard-Jones atoms) are
created. If both arguments are specified, then only a single PDB file
can be listed. It is treated as a template file, and the atom
coordinates in the data object replace the atom coordinates in the
template PDB file to create a series of new PDB files. This
replacement is only done for selected atoms (in the dump object) and
for atom IDs that appear in the PDB file.
</P>
<P>The iterator() method is called by the <A HREF = "rasmol.html">rasmol</A> tool to
create a series of PDB files for visualization purposes.
</P>
<P><B>Usage:</B>
</P>
<PRE>p = pdbfile("3CRO") create pdb object from PDB file or WWW
p = pdbfile("pep1 pep2") read in multiple PDB files
p = pdbfile("pep*") can use wildcards
p = pdbfile(d) read in snapshot data with no PDB file
p = pdbfile("3CRO",d) read in single PDB file with snapshot data
</PRE>
<PRE> string arg contains one or more PDB files
don't need .pdb suffix except wildcard must expand to file.pdb
if only one 4-char file specified and it is not found,
it will be downloaded from http://www.rcsb.org as 3CRO.pdb
d arg is object with atom coordinates (dump, data)
</PRE>
<PRE>p.one() write all output as one big PDB file to tmp.pdb
p.one("mine") write to mine.pdb
p.many() write one PDB file per snapshot: tmp0000.pdb, ...
p.many("mine") write as mine0000.pdb, mine0001.pdb, ...
p.single(N) write timestamp N as tmp.pdb
p.single(N,"new") write as new.pdb
</PRE>
<PRE> how new PDB files are created depends on constructor inputs:
if no d: one new PDB file for each file in string arg (just a copy)
if only d specified: one new PDB file per snapshot in generic format
if one file in str arg and d: one new PDB file per snapshot
using input PDB file as template
multiple input PDB files with a d is not allowed
</PRE>
<PRE>index,time,flag = p.iterator(0)
index,time,flag = p.iterator(1)
</PRE>
<PRE> iterator = loop over number of PDB files
call first time with arg = 0, thereafter with arg = 1
N = length = # of snapshots or # of input PDB files
index = index of snapshot or input PDB file (0 to N-1)
time = timestep value (time stamp for snapshot, index for multiple PDB)
flag = -1 when iteration is done, 1 otherwise
typically call p.single(time) in iterated loop to write out one PDB file
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "data.html">data</A>, <A HREF = "dump.html">dump</A>, <A HREF = "rasmol.html">rasmol</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

93
doc/pdbfile.txt Normal file
View File

@ -0,0 +1,93 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
pdbfile tool :h3
[Purpose:]
Read, write PDB files in combo with LAMMPS snapshots.
[Description:]
The pdbfile tool reads in PDB (Protein Data Bank) files of protein
coordinates and uses them in conjunction with LAMMPS snapshots in
various ways. The PDB format is commonly used by various
vizualization and analysis programs.
The pdbfile constructor takes a string argument listing one or more
PDB filenames and a data argument with LAMMPS atom information
("data"_data.html or "dump"_dump.html object). The atom snapshots
must have "id", "type", "x", "y", and "z" defined; see the map()
methods of those tools.
Both arguments to the constructor are optional, as described below.
If a single PDB file is given as a constructor argument, and it is 4
letters long, and it does not exist on your system, then it is treated
as a PDB identifier and the matching PDB file is downloaded from a PDB
repository on the WWW to your machine.
The one(), many(), and single() methods write out PDB files in various
manners, depending on the 1 or 2 arguments used in the constructor.
If only a string was specified (no data object), the specified PDB
files are written out as-is. Thus the one() method concatenates the
files together. If only a data object was specified (no string of PDB
files), then PDB files in a generic format (Lennard-Jones atoms) are
created. If both arguments are specified, then only a single PDB file
can be listed. It is treated as a template file, and the atom
coordinates in the data object replace the atom coordinates in the
template PDB file to create a series of new PDB files. This
replacement is only done for selected atoms (in the dump object) and
for atom IDs that appear in the PDB file.
The iterator() method is called by the "rasmol"_rasmol.html tool to
create a series of PDB files for visualization purposes.
[Usage:]
p = pdbfile("3CRO") create pdb object from PDB file or WWW
p = pdbfile("pep1 pep2") read in multiple PDB files
p = pdbfile("pep*") can use wildcards
p = pdbfile(d) read in snapshot data with no PDB file
p = pdbfile("3CRO",d) read in single PDB file with snapshot data :pre
string arg contains one or more PDB files
don't need .pdb suffix except wildcard must expand to file.pdb
if only one 4-char file specified and it is not found,
it will be downloaded from http://www.rcsb.org as 3CRO.pdb
d arg is object with atom coordinates (dump, data) :pre
p.one() write all output as one big PDB file to tmp.pdb
p.one("mine") write to mine.pdb
p.many() write one PDB file per snapshot: tmp0000.pdb, ...
p.many("mine") write as mine0000.pdb, mine0001.pdb, ...
p.single(N) write timestamp N as tmp.pdb
p.single(N,"new") write as new.pdb :pre
how new PDB files are created depends on constructor inputs:
if no d: one new PDB file for each file in string arg (just a copy)
if only d specified: one new PDB file per snapshot in generic format
if one file in str arg and d: one new PDB file per snapshot
using input PDB file as template
multiple input PDB files with a d is not allowed :pre
index,time,flag = p.iterator(0)
index,time,flag = p.iterator(1) :pre
iterator = loop over number of PDB files
call first time with arg = 0, thereafter with arg = 1
N = length = # of snapshots or # of input PDB files
index = index of snapshot or input PDB file (0 to N-1)
time = timestep value (time stamp for snapshot, index for multiple PDB)
flag = -1 when iteration is done, 1 otherwise
typically call p.single(time) in iterated loop to write out one PDB file :pre
[Related tools:]
"data"_data.html, "dump"_dump.html, "rasmol"_rasmol.html
[Prerequisites:] none

69
doc/plotview.html Normal file
View File

@ -0,0 +1,69 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>plotview tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Plot multiple vectors from a data set.
</P>
<P><B>Description:</B>
</P>
<P>The plotview tool displays a GUI for showing a series of plots of
vectors stored in another Pizza.py tool. Individual plots can be
displayed or hidden or saved to a file.
</P>
<P>The plotview constructor creates the GUI and takes a data object
(<A HREF = "log.html">log</A>, <A HREF = "vec.html">vec</A>) and a plot object (<A HREF = "gnu.html">gnu</A>,
<A HREF = "matlab.html">matlab</A>) as arguments.
</P>
<P>The vectors in the data object are converted to individual plots. The
2nd thru Nth vectors are each plotted against the 1st vector to create
N-1 plots. One or more plots can be displayed simultaneously (right
buttons in GUI), but only one is selected at a time (left buttons in
GUI). The yes(), no(), and select() methods perform the same function
as the GUI buttons.
</P>
<P>The currently selected plot can be modified (title, range, etc)
by the methods of the plot object.
</P>
<P>The file() and save() methods (or corresponding GUI widgets) save the
currently selected plot to a PostScript file.
</P>
<P><B>Usage:</B>
</P>
<PRE>p = plotview(d,pl) create GUI for viewing plots
</PRE>
<PRE> d = Pizza.py object that contains vectors (log, vec)
pl = Pizza.py plotting object (gnu, matlab)
</PRE>
<PRE>p.select(2) select one plot as current (1-N)
p.yes(3) toggle one plot's visibility
p.no(3)
</PRE>
<PRE> only one plot is selected at a time
multiple plots can be visible at same time
select is same as clicking on left-side radio-button
yes/no is same as clicking on right-side checkbox
</PRE>
<PRE>p.x = "Time" which vector is X vector (1st vec by default)
p.file("pressure") filename prefix for saving a plot
p.save() save currently selected plot to file.eps
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "log.html">log</A>, <A HREF = "gnu.html">gnu</A>, <A HREF = "matlab.html">matlab</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Python Tkinter package.
</P>
</HTML>

64
doc/plotview.txt Normal file
View File

@ -0,0 +1,64 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
plotview tool :h3
[Purpose:]
Plot multiple vectors from a data set.
[Description:]
The plotview tool displays a GUI for showing a series of plots of
vectors stored in another Pizza.py tool. Individual plots can be
displayed or hidden or saved to a file.
The plotview constructor creates the GUI and takes a data object
("log"_log.html, "vec"_vec.html) and a plot object ("gnu"_gnu.html,
"matlab"_matlab.html) as arguments.
The vectors in the data object are converted to individual plots. The
2nd thru Nth vectors are each plotted against the 1st vector to create
N-1 plots. One or more plots can be displayed simultaneously (right
buttons in GUI), but only one is selected at a time (left buttons in
GUI). The yes(), no(), and select() methods perform the same function
as the GUI buttons.
The currently selected plot can be modified (title, range, etc)
by the methods of the plot object.
The file() and save() methods (or corresponding GUI widgets) save the
currently selected plot to a PostScript file.
[Usage:]
p = plotview(d,pl) create GUI for viewing plots :pre
d = Pizza.py object that contains vectors (log, vec)
pl = Pizza.py plotting object (gnu, matlab) :pre
p.select(2) select one plot as current (1-N)
p.yes(3) toggle one plot's visibility
p.no(3) :pre
only one plot is selected at a time
multiple plots can be visible at same time
select is same as clicking on left-side radio-button
yes/no is same as clicking on right-side checkbox :pre
p.x = "Time" which vector is X vector (1st vec by default)
p.file("pressure") filename prefix for saving a plot
p.save() save currently selected plot to file.eps :pre
[Related tools:]
"log"_log.html, "gnu"_gnu.html, "matlab"_matlab.html
[Prerequisites:]
Python Tkinter package.

77
doc/rasmol.html Normal file
View File

@ -0,0 +1,77 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>rasmol tool
</H3>
<P><B>Purpose:</B>
</P>
<P>3d visualization via RasMol program.
</P>
<P><B>Description:</B>
</P>
<P>The rasmol tool is a wrapper on the <A HREF = "http://www.openrasmol.org">RasMol</A>
visualization program. RasMol is open source software and runs on
many platforms. The link above is for the Open Rasmol WWW site, not
the Protein Explorer WWW site. Protein Explorer is a derivative of
RasMol and runs primarily on Windows machines within a browser. This
Pizza.py tool wraps the original RasMol program, not Protein Explorer.
</P>
<P>The rasmol constructor takes a <A HREF = "pdbfile.html">pdbfile</A> object as its
argument which produces PDB files that RasMol reads in. The pdbfile
object can produce PDB files from a LAMMPS dump or data file, as well
as in other ways.
</P>
<P>The show() method runs RasMol on the atoms of snapshot N (converted to
a PDB file) and displays the resulting image stored as image.gif.
Either a default RasMol script or one you specify is used to format
the RasMol image. The all() method loops thru all selected snapshots
and runs RasMol on each one. The resulting image files are saved to
image0000.gif, image0001.gif, etc. The prefix "image" can be changed
via the file setting.
</P>
<P>A RasMol script can be created by running RasMol itself (outside of
Pizza.py), typing commands or choosing menu options to format the
display as desired, then typing "write script filename".
Alternatively the run() method will do this for you. It runs RasMol
on snapshot N and lets you interact with RasMol directly either via
typing or mouse operations in the RasMol window. When you type "quit"
or "exit" the script file will be saved (do not exit via the Rasmol
menu).
</P>
<P><B>Usage:</B>
</P>
<PRE>r = rasmol(p) create RasMol wrapper for pdb object p
</PRE>
<PRE>r.file = "image" file prefix for created images (def = "image")
</PRE>
<PRE>r.show(N) show snapshot at timestep N with default script
r.show(N,"my.rasmol") use file as RasMol script
</PRE>
<PRE>r.all() make images of all selected snapshots with def script
r.all("my.rasmol") use file as RasMol script
</PRE>
<PRE>r.run(N) run RasMol interactivly on snapshot N
r.run(N,"new.rasmol") adjust via mouse or RasMol commands
r.run(N,"new.rasmol","old.rasmol") type quit to save RasMol script file
</PRE>
<PRE> if 2 args, 2nd arg is new script file, else save to "tmp.rasmol"
if 3 args, 3rd arg is initial script file, else use default script
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "gl.html">gl</A>, <A HREF = "pdbfile.html">pdbfile</A>,
<A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>The RasMol program.
</P>
</HTML>

72
doc/rasmol.txt Normal file
View File

@ -0,0 +1,72 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
rasmol tool :h3
[Purpose:]
3d visualization via RasMol program.
[Description:]
The rasmol tool is a wrapper on the "RasMol"_http://www.openrasmol.org
visualization program. RasMol is open source software and runs on
many platforms. The link above is for the Open Rasmol WWW site, not
the Protein Explorer WWW site. Protein Explorer is a derivative of
RasMol and runs primarily on Windows machines within a browser. This
Pizza.py tool wraps the original RasMol program, not Protein Explorer.
The rasmol constructor takes a "pdbfile"_pdbfile.html object as its
argument which produces PDB files that RasMol reads in. The pdbfile
object can produce PDB files from a LAMMPS dump or data file, as well
as in other ways.
The show() method runs RasMol on the atoms of snapshot N (converted to
a PDB file) and displays the resulting image stored as image.gif.
Either a default RasMol script or one you specify is used to format
the RasMol image. The all() method loops thru all selected snapshots
and runs RasMol on each one. The resulting image files are saved to
image0000.gif, image0001.gif, etc. The prefix "image" can be changed
via the file setting.
A RasMol script can be created by running RasMol itself (outside of
Pizza.py), typing commands or choosing menu options to format the
display as desired, then typing "write script filename".
Alternatively the run() method will do this for you. It runs RasMol
on snapshot N and lets you interact with RasMol directly either via
typing or mouse operations in the RasMol window. When you type "quit"
or "exit" the script file will be saved (do not exit via the Rasmol
menu).
[Usage:]
r = rasmol(p) create RasMol wrapper for pdb object p :pre
r.file = "image" file prefix for created images (def = "image") :pre
r.show(N) show snapshot at timestep N with default script
r.show(N,"my.rasmol") use file as RasMol script :pre
r.all() make images of all selected snapshots with def script
r.all("my.rasmol") use file as RasMol script :pre
r.run(N) run RasMol interactivly on snapshot N
r.run(N,"new.rasmol") adjust via mouse or RasMol commands
r.run(N,"new.rasmol","old.rasmol") type quit to save RasMol script file :pre
if 2 args, 2nd arg is new script file, else save to "tmp.rasmol"
if 3 args, 3rd arg is initial script file, else use default script :pre
[Related tools:]
"dump"_dump.html, "gl"_gl.html, "pdbfile"_pdbfile.html,
"raster"_raster.html, "svg"_svg.html
[Prerequisites:]
The RasMol program.

156
doc/raster.html Normal file
View File

@ -0,0 +1,156 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>raster tool
</H3>
<P><B>Purpose:</B>
</P>
<P>3d visualization via Raster3d program.
</P>
<P><B>Description:</B>
</P>
<P>The raster tool is a wrapper on the
<A HREF = "http://www.bmsc.washington.edu/raster3d/raster3d.html">Raster3d</A>
visualization program. Raster3d is open source software and runs on
many platforms.
</P>
<P>The raster constructor takes a data object containing atom or mesh
snapshots as an argument (<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>,
<A HREF = "cdata.html">cdata</A>, <A HREF = "mdump.html">mdump</A>).
</P>
<P>The show() method runs Raster3d on the selected atoms or triangles of
snapshot N and displays the resulting image stored as image.png. The
all() method loops thru all selected snapshots and runs Raster3d on
each one. The resulting image files are saved to image0000.png,
image0001.png, etc. The prefix "image" can be changed via the file
setting.
</P>
<P>The bg(), size(), rotate(), trans(), zoom(), box(), label(), and
nolabel() methods control various aspects of the images produced.
Without the trans() and zoom() settings, the Raster3d image should
roughly fill the window and be centered.
</P>
<P>Additional movie effects can be produced using the pan() and select()
methods. The pan() method specifies an initial and final viewpoint
that is applied to the images produced by the all() method. For
intermediate images, the view parameters will be interpolated between
their initial and final values. The pan() method can thus be used to
rotate a single image or fly-by the simulation as it animates. The
select() method performs additional atom selection for each image of
the all() sequence. An image-dependent %g variable can be used in the
select() string. The select() method can thus be used to slice thru
the data set.
</P>
<P>The acol(), arad(), bcol(), brad(), and tcol() methods change
attributes of the atoms, bonds, and triangles displayed. Each atom or
bond returned from the data object has an integer "type" from 1 to N.
The type is used to index into a list of RGB colors or radii for atoms
and bond thickness. The adef(), bdef(), and tdef() methods setup
default mappings of types to colors/radii. The other methods enable
specific assignments to be made. The interpolation option (e.g. many
types assigned to a few colors), enables a smooth rainbow of colors to
be assigned to a range of types. Note that the <A HREF = "dump.html">dump</A> tool
allows any vector to be returned as an atom "type" via its atype
setting. Thus displayed colors can be keyed to atom velocity or other
properties.
</P>
<P>Colors are specified with a string, e.g. "red". There are 140
pre-defined colors from <A HREF = "http://www.oreilly.com/catalog/wdnut/excerpt/color_names.html">this WWW page</A> which can be
examined by importing the "colors" variable from "vizinfo". New
colors can be defined by assigning a nickname of your choice to an RGB
triplet, as described below.
</P>
<P><B>Usage:</B>
</P>
<PRE>r = raster(d) create Raster3d wrapper for data in d
</PRE>
<PRE> d = atom snapshot object (dump, data)
</PRE>
<PRE>r.bg("black") set background color (def = "black")
r.size(N) set image size to NxN
r.size(N,M) set image size to NxM
r.rotate(60,135) view from z theta and azimuthal phi (def = 60,30)
r.shift(x,y) translate by x,y pixels in view window (def = 0,0)
r.zoom(0.5) scale image by factor (def = 1)
r.box(0/1/2) 0/1/2 = none/variable/fixed box
r.box(0/1/2,"green") set box color
r.box(0/1/2,"red",4) set box edge thickness
r.file = "image" file prefix for created images (def = "image")
</PRE>
<PRE>r.show(N) show image of snapshot at timestep N
</PRE>
<PRE>r.all() make images of all selected snapshots
r.all(P) images of all, start file label at P
r.all(N,M,P) make M images of snapshot N, start label at P
</PRE>
<PRE>r.pan(60,135,1.0,40,135,1.5) pan during all() operation
r.pan() no pan during all() (default)
</PRE>
<PRE> args = z theta, azimuthal phi, zoom factor at beginning and end
values at each step are interpolated between beginning and end values
</PRE>
<PRE>r.select = "$x > %g*3.0" string to pass to d.aselect.test() during all()
r.select = "" no extra aselect (default)
</PRE>
<PRE> %g varies from 0.0 to 1.0 from beginning to end of all()
</PRE>
<PRE>r.label(x,y,"h",size,"red","This is a label") add label to each image
r.nolabel() delete all labels
</PRE>
<PRE> x,y coords = -0.5 to 0.5, "h" or "t" for Helvetica or Times font
size = fontsize (e.g. 10), "red" = color of text
</PRE>
<PRE>r.acol(2,"green") set atom colors by atom type (1-N)
r.acol([2,4],["red","blue"]) 1st arg = one type or list of types
r.acol(0,"blue") 2nd arg = one color or list of colors
r.acol(range(20),["red","blue"]) if list lengths unequal, interpolate
r.acol(range(10),"loop") assign colors in loop, randomly ordered
</PRE>
<PRE> if 1st arg is 0, set all types to 2nd arg
if list of types has a 0 (e.g. range(10)), +1 is added to each value
interpolate means colors blend smoothly from one value to the next
</PRE>
<PRE>r.arad([1,2],[0.5,0.3]) set atom radii, same rules as acol()
</PRE>
<PRE>r.bcol() set bond color, same args as acol()
r.brad() set bond thickness, same args as arad()
</PRE>
<PRE>r.tcol() set triangle color, same args as acol()
r.tfill() set triangle fill, 0 fill, 1 line, 2 both
</PRE>
<PRE>r.lcol() set line color, same args as acol()
r.lrad() set line thickness, same args as arad()
</PRE>
<PRE>r.adef() set atom/bond/tri/line properties to default
r.bdef() default = "loop" for colors, 0.45 for radii
r.tdef() default = 0.25 for bond/line thickness
r.ldef() default = 0 fill
</PRE>
<PRE> by default 100 types are assigned
if atom/bond/tri/line has type > # defined properties, is an error
</PRE>
<PRE>from vizinfo import colors access color list
print colors list defined color names and RGB values
colors["nickname"] = [R,G,B] set new RGB values from 0 to 255
</PRE>
<PRE> 140 pre-defined colors: red, green, blue, purple, yellow, black, white, etc
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "gl.html">gl</A>, <A HREF = "rasmol.html">rasmol</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>The Raster3d render and label3d programs.
</P>
</HTML>

151
doc/raster.txt Normal file
View File

@ -0,0 +1,151 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
raster tool :h3
[Purpose:]
3d visualization via Raster3d program.
[Description:]
The raster tool is a wrapper on the
"Raster3d"_http://www.bmsc.washington.edu/raster3d/raster3d.html
visualization program. Raster3d is open source software and runs on
many platforms.
The raster constructor takes a data object containing atom or mesh
snapshots as an argument ("dump"_dump.html, "data"_data.html,
"cdata"_cdata.html, "mdump"_mdump.html).
The show() method runs Raster3d on the selected atoms or triangles of
snapshot N and displays the resulting image stored as image.png. The
all() method loops thru all selected snapshots and runs Raster3d on
each one. The resulting image files are saved to image0000.png,
image0001.png, etc. The prefix "image" can be changed via the file
setting.
The bg(), size(), rotate(), trans(), zoom(), box(), label(), and
nolabel() methods control various aspects of the images produced.
Without the trans() and zoom() settings, the Raster3d image should
roughly fill the window and be centered.
Additional movie effects can be produced using the pan() and select()
methods. The pan() method specifies an initial and final viewpoint
that is applied to the images produced by the all() method. For
intermediate images, the view parameters will be interpolated between
their initial and final values. The pan() method can thus be used to
rotate a single image or fly-by the simulation as it animates. The
select() method performs additional atom selection for each image of
the all() sequence. An image-dependent %g variable can be used in the
select() string. The select() method can thus be used to slice thru
the data set.
The acol(), arad(), bcol(), brad(), and tcol() methods change
attributes of the atoms, bonds, and triangles displayed. Each atom or
bond returned from the data object has an integer "type" from 1 to N.
The type is used to index into a list of RGB colors or radii for atoms
and bond thickness. The adef(), bdef(), and tdef() methods setup
default mappings of types to colors/radii. The other methods enable
specific assignments to be made. The interpolation option (e.g. many
types assigned to a few colors), enables a smooth rainbow of colors to
be assigned to a range of types. Note that the "dump"_dump.html tool
allows any vector to be returned as an atom "type" via its atype
setting. Thus displayed colors can be keyed to atom velocity or other
properties.
Colors are specified with a string, e.g. "red". There are 140
pre-defined colors from "this WWW page"_colortable which can be
examined by importing the "colors" variable from "vizinfo". New
colors can be defined by assigning a nickname of your choice to an RGB
triplet, as described below.
:link(colortable,http://www.oreilly.com/catalog/wdnut/excerpt/color_names.html)
[Usage:]
r = raster(d) create Raster3d wrapper for data in d :pre
d = atom snapshot object (dump, data) :pre
r.bg("black") set background color (def = "black")
r.size(N) set image size to NxN
r.size(N,M) set image size to NxM
r.rotate(60,135) view from z theta and azimuthal phi (def = 60,30)
r.shift(x,y) translate by x,y pixels in view window (def = 0,0)
r.zoom(0.5) scale image by factor (def = 1)
r.box(0/1/2) 0/1/2 = none/variable/fixed box
r.box(0/1/2,"green") set box color
r.box(0/1/2,"red",4) set box edge thickness
r.file = "image" file prefix for created images (def = "image") :pre
r.show(N) show image of snapshot at timestep N :pre
r.all() make images of all selected snapshots
r.all(P) images of all, start file label at P
r.all(N,M,P) make M images of snapshot N, start label at P :pre
r.pan(60,135,1.0,40,135,1.5) pan during all() operation
r.pan() no pan during all() (default) :pre
args = z theta, azimuthal phi, zoom factor at beginning and end
values at each step are interpolated between beginning and end values :pre
r.select = "$x > %g*3.0" string to pass to d.aselect.test() during all()
r.select = "" no extra aselect (default) :pre
%g varies from 0.0 to 1.0 from beginning to end of all() :pre
r.label(x,y,"h",size,"red","This is a label") add label to each image
r.nolabel() delete all labels :pre
x,y coords = -0.5 to 0.5, "h" or "t" for Helvetica or Times font
size = fontsize (e.g. 10), "red" = color of text :pre
r.acol(2,"green") set atom colors by atom type (1-N)
r.acol(\[2,4\],\["red","blue"\]) 1st arg = one type or list of types
r.acol(0,"blue") 2nd arg = one color or list of colors
r.acol(range(20),\["red","blue"\]) if list lengths unequal, interpolate
r.acol(range(10),"loop") assign colors in loop, randomly ordered :pre
if 1st arg is 0, set all types to 2nd arg
if list of types has a 0 (e.g. range(10)), +1 is added to each value
interpolate means colors blend smoothly from one value to the next :pre
r.arad(\[1,2\],\[0.5,0.3\]) set atom radii, same rules as acol() :pre
r.bcol() set bond color, same args as acol()
r.brad() set bond thickness, same args as arad() :pre
r.tcol() set triangle color, same args as acol()
r.tfill() set triangle fill, 0 fill, 1 line, 2 both :pre
r.lcol() set line color, same args as acol()
r.lrad() set line thickness, same args as arad() :pre
r.adef() set atom/bond/tri/line properties to default
r.bdef() default = "loop" for colors, 0.45 for radii
r.tdef() default = 0.25 for bond/line thickness
r.ldef() default = 0 fill :pre
by default 100 types are assigned
if atom/bond/tri/line has type > # defined properties, is an error :pre
from vizinfo import colors access color list
print colors list defined color names and RGB values
colors\["nickname"\] = \[R,G,B\] set new RGB values from 0 to 255 :pre
140 pre-defined colors: red, green, blue, purple, yellow, black, white, etc :pre
[Related tools:]
"dump"_dump.html, "gl"_gl.html, "rasmol"_rasmol.html, "svg"_svg.html
[Prerequisites:]
The Raster3d render and label3d programs.

158
doc/svg.html Normal file
View File

@ -0,0 +1,158 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>svg tool
</H3>
<P><B>Purpose:</B>
</P>
<P>3d visualization via SVG files.
</P>
<P><B>Description:</B>
</P>
<P>The svg tool creates Scalable Vector Graphics
(<A HREF = "http://www.w3.org/Graphics/SVG">SVG</A>) files from atom or mesh
snapshots. The SVG format can be displayed or animated by various
tools and is a popular format for viewing solid state lattices.
</P>
<P>The svg constructor takes a data object containing atom or mesh
snapshots as an argument (<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>,
<A HREF = "cdata.html">cdata</A>, <A HREF = "mdump.html">mdump</A>).
</P>
<P>The show() method creates an image.svg file for snapshot N. The all()
method loops thru all selected snapshots and creates the image files
image0000.svg, image0001.svg, etc. The prefix "image" can be changed
via the file setting.
</P>
<P>The bg(), size(), rotate(), trans(), zoom(), box(), label(), and
nolabel() methods control various aspects of the images produced.
Without the trans() and zoom() settings, the Raster3d image should
roughly fill the window and be centered.
</P>
<P>Additional movie effects can be produced using the pan() and select()
methods. The pan() method specifies an initial and final viewpoint
that is applied to the images produced by the all() method. For
intermediate images, the view parameters will be interpolated between
their initial and final values. The pan() method can thus be used to
rotate a single image or fly-by the simulation as it animates. The
select() method performs additional atom selection for each image of
the all() sequence. An image-dependent %g variable can be used in the
select() string. The select() method can thus be used to slice thru
the data set.
</P>
<P>The acol(), arad(), bcol(), brad(), and tcol() methods change
attributes of the atoms, bonds, and triangles displayed. Each atom or
bond returned from the data object has an integer "type" from 1 to N.
The type is used to index into a list of RGB colors or radii for atoms
and bond thickness. The adef(), bdef(), and tdef() methods setup
default mappings of types to colors/radii. The other methods enable
specific assignments to be made. The interpolation option (e.g. many
types assigned to a few colors), enables a smooth rainbow of colors to
be assigned to a range of types. Note that the <A HREF = "dump.html">dump</A> tool
allows any vector to be returned as an atom "type" via its atype
setting. Thus displayed colors can be keyed to atom velocity or other
properties.
</P>
<P>Colors are specified with a string, e.g. "red". There are 140
pre-defined colors from <A HREF = "http://www.oreilly.com/catalog/wdnut/excerpt/color_names.html">this WWW page</A> which can be
examined by importing the "colors" variable from "vizinfo". New
colors can be defined by assigning a nickname of your choice to an RGB
triplet, as described below.
</P>
<P><B>Usage:</B>
</P>
<PRE>s = svg(d) create SVG object for data in d
</PRE>
<PRE> d = atom snapshot object (dump, data)
</PRE>
<PRE>s.bg("black") set background color (def = "black")
s.size(N) set image size to NxN
s.size(N,M) set image size to NxM
s.rotate(60,135) view from z theta and azimuthal phi (def = 60,30)
s.shift(x,y) translate by x,y pixels in view window (def = 0,0)
s.zoom(0.5) scale image by factor (def = 1)
s.box(0/1/2) 0/1/2 = none/variable/fixed box
s.box(0/1/2,"green") set box color
s.box(0/1/2,"red",4) set box edge thickness
s.file = "image" file prefix for created images (def = "image")
</PRE>
<PRE>s.show(N) show image of snapshot at timestep N
</PRE>
<PRE>s.all() make images of all selected snapshots
s.all(P) images of all, start file label at P
s.all(N,M,P) make M images of snapshot N, start label at P
</PRE>
<PRE>s.pan(60,135,1.0,40,135,1.5) pan during all() operation
s.pan() no pan during all() (default)
</PRE>
<PRE> args = z theta, azimuthal phi, zoom factor at beginning and end
values at each step are interpolated between beginning and end values
</PRE>
<PRE>s.select = "$x > %g*3.0" string to pass to d.aselect.test() during all()
s.select = "" no extra aselect (default)
</PRE>
<PRE> %g varies from 0.0 to 1.0 from beginning to end of all()
</PRE>
<PRE>s.label(x,y,"h",size,"red","This is a label") add label to each image
s.nolabel() delete all labels
</PRE>
<PRE> x,y coords = -0.5 to 0.5, "h" or "t" for Helvetica or Times font
size = fontsize (e.g. 10), "red" = color of text
</PRE>
<PRE>s.acol(2,"green") set atom colors by atom type (1-N)
s.acol([2,4],["red","blue"]) 1st arg = one type or list of types
s.acol(0,"blue") 2nd arg = one color or list of colors
s.acol(range(20),["red","blue"]) if list lengths unequal, interpolate
s.acol(range(10),"loop") assign colors in loop, randomly ordered
</PRE>
<PRE> if 1st arg is 0, set all types to 2nd arg
if list of types has a 0 (e.g. range(10)), +1 is added to each value
interpolate means colors blend smoothly from one value to the next
</PRE>
<PRE>s.arad([1,2],[0.5,0.3]) set atom radii, same rules as acol()
</PRE>
<PRE>s.bcol() set bond color, same args as acol()
s.brad() set bond thickness, same args as arad()
</PRE>
<PRE>s.tcol() set triangle color, same args as acol()
s.tfill() set triangle fill, 0 fill, 1 line, 2 both
</PRE>
<PRE>s.lcol() set line color, same args as acol()
s.lrad() set line thickness, same args as arad()
</PRE>
<PRE>s.adef() set atom/bond/tri/line properties to default
s.bdef() default = "loop" for colors, 0.45 for radii
s.tdef() default = 0.25 for bond/line thickness
s.ldef() default = 0 fill
</PRE>
<PRE> by default 100 types are assigned
if atom/bond/tri/line has type > # defined properties, is an error
</PRE>
<PRE>from vizinfo import colors access color list
print colors list defined color names and RGB values
colors["nickname"] = [R,G,B] set new RGB values from 0 to 255
</PRE>
<PRE> 140 pre-defined colors: red, green, blue, purple, yellow, black, white, etc
</PRE>
<PRE>Settings specific to svg tool:
</PRE>
<PRE>s.thick = 2.0 pixel thickness of black atom border
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "gl.html">gl</A>, <A HREF = "raster.html">raster</A>, <A HREF = "rasmol.html">rasmol</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Display program for viewing *.svg image files.
</P>
</HTML>

153
doc/svg.txt Normal file
View File

@ -0,0 +1,153 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
svg tool :h3
[Purpose:]
3d visualization via SVG files.
[Description:]
The svg tool creates Scalable Vector Graphics
("SVG"_http://www.w3.org/Graphics/SVG) files from atom or mesh
snapshots. The SVG format can be displayed or animated by various
tools and is a popular format for viewing solid state lattices.
The svg constructor takes a data object containing atom or mesh
snapshots as an argument ("dump"_dump.html, "data"_data.html,
"cdata"_cdata.html, "mdump"_mdump.html).
The show() method creates an image.svg file for snapshot N. The all()
method loops thru all selected snapshots and creates the image files
image0000.svg, image0001.svg, etc. The prefix "image" can be changed
via the file setting.
The bg(), size(), rotate(), trans(), zoom(), box(), label(), and
nolabel() methods control various aspects of the images produced.
Without the trans() and zoom() settings, the Raster3d image should
roughly fill the window and be centered.
Additional movie effects can be produced using the pan() and select()
methods. The pan() method specifies an initial and final viewpoint
that is applied to the images produced by the all() method. For
intermediate images, the view parameters will be interpolated between
their initial and final values. The pan() method can thus be used to
rotate a single image or fly-by the simulation as it animates. The
select() method performs additional atom selection for each image of
the all() sequence. An image-dependent %g variable can be used in the
select() string. The select() method can thus be used to slice thru
the data set.
The acol(), arad(), bcol(), brad(), and tcol() methods change
attributes of the atoms, bonds, and triangles displayed. Each atom or
bond returned from the data object has an integer "type" from 1 to N.
The type is used to index into a list of RGB colors or radii for atoms
and bond thickness. The adef(), bdef(), and tdef() methods setup
default mappings of types to colors/radii. The other methods enable
specific assignments to be made. The interpolation option (e.g. many
types assigned to a few colors), enables a smooth rainbow of colors to
be assigned to a range of types. Note that the "dump"_dump.html tool
allows any vector to be returned as an atom "type" via its atype
setting. Thus displayed colors can be keyed to atom velocity or other
properties.
Colors are specified with a string, e.g. "red". There are 140
pre-defined colors from "this WWW page"_colortable which can be
examined by importing the "colors" variable from "vizinfo". New
colors can be defined by assigning a nickname of your choice to an RGB
triplet, as described below.
:link(colortable,http://www.oreilly.com/catalog/wdnut/excerpt/color_names.html)
[Usage:]
s = svg(d) create SVG object for data in d :pre
d = atom snapshot object (dump, data) :pre
s.bg("black") set background color (def = "black")
s.size(N) set image size to NxN
s.size(N,M) set image size to NxM
s.rotate(60,135) view from z theta and azimuthal phi (def = 60,30)
s.shift(x,y) translate by x,y pixels in view window (def = 0,0)
s.zoom(0.5) scale image by factor (def = 1)
s.box(0/1/2) 0/1/2 = none/variable/fixed box
s.box(0/1/2,"green") set box color
s.box(0/1/2,"red",4) set box edge thickness
s.file = "image" file prefix for created images (def = "image") :pre
s.show(N) show image of snapshot at timestep N :pre
s.all() make images of all selected snapshots
s.all(P) images of all, start file label at P
s.all(N,M,P) make M images of snapshot N, start label at P :pre
s.pan(60,135,1.0,40,135,1.5) pan during all() operation
s.pan() no pan during all() (default) :pre
args = z theta, azimuthal phi, zoom factor at beginning and end
values at each step are interpolated between beginning and end values :pre
s.select = "$x > %g*3.0" string to pass to d.aselect.test() during all()
s.select = "" no extra aselect (default) :pre
%g varies from 0.0 to 1.0 from beginning to end of all() :pre
s.label(x,y,"h",size,"red","This is a label") add label to each image
s.nolabel() delete all labels :pre
x,y coords = -0.5 to 0.5, "h" or "t" for Helvetica or Times font
size = fontsize (e.g. 10), "red" = color of text :pre
s.acol(2,"green") set atom colors by atom type (1-N)
s.acol(\[2,4\],\["red","blue"\]) 1st arg = one type or list of types
s.acol(0,"blue") 2nd arg = one color or list of colors
s.acol(range(20),\["red","blue"\]) if list lengths unequal, interpolate
s.acol(range(10),"loop") assign colors in loop, randomly ordered :pre
if 1st arg is 0, set all types to 2nd arg
if list of types has a 0 (e.g. range(10)), +1 is added to each value
interpolate means colors blend smoothly from one value to the next :pre
s.arad(\[1,2\],\[0.5,0.3\]) set atom radii, same rules as acol() :pre
s.bcol() set bond color, same args as acol()
s.brad() set bond thickness, same args as arad() :pre
s.tcol() set triangle color, same args as acol()
s.tfill() set triangle fill, 0 fill, 1 line, 2 both :pre
s.lcol() set line color, same args as acol()
s.lrad() set line thickness, same args as arad() :pre
s.adef() set atom/bond/tri/line properties to default
s.bdef() default = "loop" for colors, 0.45 for radii
s.tdef() default = 0.25 for bond/line thickness
s.ldef() default = 0 fill :pre
by default 100 types are assigned
if atom/bond/tri/line has type > # defined properties, is an error :pre
from vizinfo import colors access color list
print colors list defined color names and RGB values
colors\["nickname"\] = \[R,G,B\] set new RGB values from 0 to 255 :pre
140 pre-defined colors: red, green, blue, purple, yellow, black, white, etc :pre
Settings specific to svg tool: :pre
s.thick = 2.0 pixel thickness of black atom border :pre
[Related tools:]
"dump"_dump.html, "gl"_gl.html, "raster"_raster.html, "rasmol"_rasmol.html
[Prerequisites:]
Display program for viewing *.svg image files.

122
doc/tdump.html Normal file
View File

@ -0,0 +1,122 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>tdump tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Read dump files with triangle info.
</P>
<P><B>Description:</B>
</P>
<P>The tdump tool reads one or more LAMMPS dump files, and stores their
contents as a series of snapshots with 2d arrays of atom attributes.
It is assumed that each atom contains triangle segment info from a
LAMMPS simulation using atom_style tri. Other tools use tdump objects
to extract triangle info for visualization, like the dump tool via its
extra() method.
</P>
<P>The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
</P>
<P>The map() method assigns names to columns of atom attributes. The
id,type, corner1x,corner1y,corner1z, corner2x,corner2y,corner2z,
corner3x,corner3y,corner3z names must be assigned in order for line
segment info to be extracted.
</P>
<P>The viz() method is called by Pizza.py tools that visualize snapshots
of atoms (e.g. gl, raster, svg tools).
</P>
<HR>
<P>Normally, <A HREF = "http://lammps.sandia.gov">LAMMPS</A> creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump files is simple. Each snapshot is formatted as
follows:
</P>
<PRE>ITEM: TIMESTEP
100
ITEM: NUMBER OF ATOMS
32
ITEM: BOX BOUNDS
0 3.35919
0 3.35919
0 7.50
ITEM: ATOMS
1 1 0 0 0
2 1 0.25 0.25 0
3 1 0.25 0 0.25
...
N 3 0.7 0.5 0.6
</PRE>
<P>The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
ATOMS" where N is the number of atoms. Atoms do not have to be listed
in any particular order. There can be a different number of atoms in
each snapshot. Each line must contain the atom ID, type, and the end
points of the associated line segment, as specified by the map()
command.
</P>
<HR>
<P><B>Usage:</B>
</P>
<PRE>t = tdump("dump.one") read in one or more dump files
t = tdump("dump.1 dump.2.gz") can be gzipped
t = tdump("dump.*") wildcard expands to multiple files
t = tdump("dump.*",0) two args = store filenames, but don't read
</PRE>
<PRE> incomplete and duplicate snapshots are deleted
no column name assignment is performed
</PRE>
<PRE>time = t.next() read next snapshot from dump files
</PRE>
<PRE> used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment is performed
</PRE>
<PRE>t.map(1,"id",3,"x") assign names to atom columns (1-N)
</PRE>
<PRE> must assign id,type,corner1x,corner1y,corner1z,corner2x,corner2y,corner2z,corner3x,corner3y,corner3z
</PRE>
<PRE>time,box,atoms,bonds,tris,lines = t.viz(index) return list of viz objects
</PRE>
<PRE> viz() returns line info for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \[xlo,ylo,zlo,xhi,yhi,zhi\]
atoms = NULL
bonds = NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3 for each tri as 2d array
id,type are from associated atom
lines = NULL
</PRE>
<PRE>t.owrap(...) wrap tris to same image as their atoms
</PRE>
<PRE> owrap() is called by dump tool's owrap()
useful for wrapping all molecule's atoms/tris the same so it is contiguous
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "gl.html">gl</A>, <A HREF = "raster.html">raster</A>, <A HREF = "svg.html">svg</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).
</P>
</HTML>

117
doc/tdump.txt Normal file
View File

@ -0,0 +1,117 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
tdump tool :h3
[Purpose:]
Read dump files with triangle info.
[Description:]
The tdump tool reads one or more LAMMPS dump files, and stores their
contents as a series of snapshots with 2d arrays of atom attributes.
It is assumed that each atom contains triangle segment info from a
LAMMPS simulation using atom_style tri. Other tools use tdump objects
to extract triangle info for visualization, like the dump tool via its
extra() method.
The constructor method is passed a string containing one or more dump
filenames. They can be listed in any order since snapshots are sorted
by timestep after they are read and duplicate snapshots (with the same
time stamp) are deleted. If a 2nd argument is specified, the files
are not immediately read, but snapshots can be read one-at-a-time by
the next() method.
The map() method assigns names to columns of atom attributes. The
id,type, corner1x,corner1y,corner1z, corner2x,corner2y,corner2z,
corner3x,corner3y,corner3z names must be assigned in order for line
segment info to be extracted.
The viz() method is called by Pizza.py tools that visualize snapshots
of atoms (e.g. gl, raster, svg tools).
:line
Normally, "LAMMPS"_http://lammps.sandia.gov creates the dump files
read in by this tool. If you want to create them yourself, the format
of LAMMPS dump files is simple. Each snapshot is formatted as
follows:
ITEM: TIMESTEP
100
ITEM: NUMBER OF ATOMS
32
ITEM: BOX BOUNDS
0 3.35919
0 3.35919
0 7.50
ITEM: ATOMS
1 1 0 0 0
2 1 0.25 0.25 0
3 1 0.25 0 0.25
...
N 3 0.7 0.5 0.6 :pre
The box bounds are listed as xlo xhi on the 1st line, ylo yhi on the
next line, zlo zhi on the last. There are N lines following "ITEM:
ATOMS" where N is the number of atoms. Atoms do not have to be listed
in any particular order. There can be a different number of atoms in
each snapshot. Each line must contain the atom ID, type, and the end
points of the associated line segment, as specified by the map()
command.
:line
[Usage:]
t = tdump("dump.one") read in one or more dump files
t = tdump("dump.1 dump.2.gz") can be gzipped
t = tdump("dump.*") wildcard expands to multiple files
t = tdump("dump.*",0) two args = store filenames, but don't read :pre
incomplete and duplicate snapshots are deleted
no column name assignment is performed :pre
time = t.next() read next snapshot from dump files :pre
used with 2-argument constructor to allow reading snapshots one-at-a-time
snapshot will be skipped only if another snapshot has same time stamp
return time stamp of snapshot read
return -1 if no snapshots left or last snapshot is incomplete
no column name assignment is performed :pre
t.map(1,"id",3,"x") assign names to atom columns (1-N) :pre
must assign id,type,corner1x,corner1y,corner1z,corner2x,corner2y,corner2z,corner3x,corner3y,corner3z :pre
time,box,atoms,bonds,tris,lines = t.viz(index) return list of viz objects :pre
viz() returns line info for specified timestep index
can also call as viz(time,1) and will find index of preceding snapshot
time = timestep value
box = \\[xlo,ylo,zlo,xhi,yhi,zhi\\]
atoms = NULL
bonds = NULL
tris = id,type,x1,y1,z1,x2,y2,z2,x3,y3,z3 for each tri as 2d array
id,type are from associated atom
lines = NULL :pre
t.owrap(...) wrap tris to same image as their atoms :pre
owrap() is called by dump tool's owrap()
useful for wrapping all molecule's atoms/tris the same so it is contiguous :pre
[Related tools:]
"dump"_dump.html, "gl"_gl.html, "raster"_raster.html, "svg"_svg.html
[Prerequisites:]
Numeric or NumPy Python packages. Gunzip command (if you want to read
gzipped files).

BIN
doc/tools.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

94
doc/vcr.html Normal file
View File

@ -0,0 +1,94 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>vcr tool
</H3>
<P><B>Purpose:</B>
</P>
<P>VCR-style GUI for 3d interactive OpenGL visualization.
</P>
<P><B>Description:</B>
</P>
<P>The vcr tool displays a GUI to do 3d interactive visualization of
LAMMPS snapshots or data files. It is a wrapper on the <A HREF = "gl.html">gl</A>
tool which draws the individual images in OpenGL windows
</P>
<P>The vcr constructor creates the GUI. Note that multiple OpenGL
windows can be run by the same GUI so that multiple views of the same
data set can be manipulated simultaneously (or views of different data
sets so long as they have the same # of snapshots).
</P>
<P>The view can be controlled by the GUI widgets or by invoking the tool
methods: play(), stop(), axis(), etc. The frame slider can be dragged
to view a desired frame. The mouse can also be used in the OpenGL
window to translage, rotate, or zoom the scene. The clipping sliders
or methods can be used to narrow the view of displayed data, though
their interactivity can be slow for scenes with lots of data.
</P>
<P>The reload() method is needed if you change the selection attributes
of the underlying data assigned to the <A HREF = "gl.html">gl</A> tool, such as via
the <A HREF = "dump.html">dump</A> tool's methods. These changes will not be
visible in the OpenGL windows until the data is reloaded.
</P>
<P>The save() method will save the current OpenGL window contents
to a PNG file. If multiple OpenGL windows are being used, multiple
files will be created. The save-all checkbox or method will store one
file per snapshot if the Play or Back buttons are used to start an
animation.
</P>
<P><B>Usage:</B>
</P>
<PRE>v = vcr(gl1,gl2,...) start vcr GUI with one or more gl windows
v.add(gl) add a gl window to vcr GUI
</PRE>
<PRE>Actions (same as GUI widgets):
</PRE>
<PRE>v.first() go to first frame
v.prev() go to previous frame
v.back() play backwards from current frame to start
v.stop() stop on current frame
v.play() play from current frame to end
v.next() go to next frame
v.last() go to last frame
</PRE>
<PRE>v.frame(31) set frame slider
v.delay(0.4) set delay slider
v.q(5) set quality slider
</PRE>
<PRE>v.xaxis() view scene from x axis
v.yaxis() view scene from y axis
v.zaxis() view scene from z axis
v.box() toggle bounding box
v.axis() toggle display of xyz axes
v.norm() recenter and resize the view
v.ortho() toggle ortho/perspective button
v.reload() reload all frames from gl viewer data files
</PRE>
<PRE>v.clipxlo(0.2) clip scene at x lo fraction of box
v.clipxhi(1.0) clip at x hi
v.clipylo(0.2) clip in y
v.clipyhi(1.0)
v.clipzlo(0.2) clip in z
v.clipzhi(1.0)
</PRE>
<PRE>v.save() save current scene to file.png
v.file("image") set filename
v.saveall() toggle save-all checkbox
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "animate.html">animate</A>, <A HREF = "gl.html">gl</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Python Tkinter package.
</P>
</HTML>

89
doc/vcr.txt Normal file
View File

@ -0,0 +1,89 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
vcr tool :h3
[Purpose:]
VCR-style GUI for 3d interactive OpenGL visualization.
[Description:]
The vcr tool displays a GUI to do 3d interactive visualization of
LAMMPS snapshots or data files. It is a wrapper on the "gl"_gl.html
tool which draws the individual images in OpenGL windows
The vcr constructor creates the GUI. Note that multiple OpenGL
windows can be run by the same GUI so that multiple views of the same
data set can be manipulated simultaneously (or views of different data
sets so long as they have the same # of snapshots).
The view can be controlled by the GUI widgets or by invoking the tool
methods: play(), stop(), axis(), etc. The frame slider can be dragged
to view a desired frame. The mouse can also be used in the OpenGL
window to translage, rotate, or zoom the scene. The clipping sliders
or methods can be used to narrow the view of displayed data, though
their interactivity can be slow for scenes with lots of data.
The reload() method is needed if you change the selection attributes
of the underlying data assigned to the "gl"_gl.html tool, such as via
the "dump"_dump.html tool's methods. These changes will not be
visible in the OpenGL windows until the data is reloaded.
The save() method will save the current OpenGL window contents
to a PNG file. If multiple OpenGL windows are being used, multiple
files will be created. The save-all checkbox or method will store one
file per snapshot if the Play or Back buttons are used to start an
animation.
[Usage:]
v = vcr(gl1,gl2,...) start vcr GUI with one or more gl windows
v.add(gl) add a gl window to vcr GUI :pre
Actions (same as GUI widgets): :pre
v.first() go to first frame
v.prev() go to previous frame
v.back() play backwards from current frame to start
v.stop() stop on current frame
v.play() play from current frame to end
v.next() go to next frame
v.last() go to last frame :pre
v.frame(31) set frame slider
v.delay(0.4) set delay slider
v.q(5) set quality slider :pre
v.xaxis() view scene from x axis
v.yaxis() view scene from y axis
v.zaxis() view scene from z axis
v.box() toggle bounding box
v.axis() toggle display of xyz axes
v.norm() recenter and resize the view
v.ortho() toggle ortho/perspective button
v.reload() reload all frames from gl viewer data files :pre
v.clipxlo(0.2) clip scene at x lo fraction of box
v.clipxhi(1.0) clip at x hi
v.clipylo(0.2) clip in y
v.clipyhi(1.0)
v.clipzlo(0.2) clip in z
v.clipzhi(1.0) :pre
v.save() save current scene to file.png
v.file("image") set filename
v.saveall() toggle save-all checkbox :pre
[Related tools:]
"animate"_animate.html, "gl"_gl.html
[Prerequisites:]
Python Tkinter package.

60
doc/vec.html Normal file
View File

@ -0,0 +1,60 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>vec tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Create numeric vectors from columns in file or list of vecs.
</P>
<P><B>Description:</B>
</P>
<P>The vec tool creates numeric vectors that can be extracted, written to
files, or imported into other tools like <A HREF = "plotview.html">plotview</A> for
plotting.
</P>
<P>The vec constructor takes either a file or list argument. For a file
argument, columns of numeric data are read from the file. Blank lines
or lines that do not start with a numeric character (0123456789.-) are
skipped. Each column must have the same number of values. For a list
argument, each element of the list is assumed to be a vector of values
(i.e. the list is a list of lists), as shown in the example below.
</P>
<P>The columns of data may be accessed by number (1-N) or by name ("col1"
thru "colN").
</P>
<P>The get() and write() methods extract the numeric vectors of data.
</P>
<P><B>Usage:</B>
</P>
<PRE>v = vec("file1") read in numeric vectors from a file
v = vec(array) array = list of numeric vectors
</PRE>
<PRE> skip blank lines and lines that start with non-numeric characters
example array with 2 vecs = [[1,2,3,4,5], [10,20,30,40,50]]
assigns names = "col1", "col2", etc
</PRE>
<PRE>nvec = v.nvec # of vectors
nlen = v.nlen lengths of vectors
names = v.names list of vector names
x,y,... = l.get(1,"col2",...) return one or more vectors of values
l.write("file.txt") write all vectors to a file
l.write("file.txt","col1",7,...) write listed vectors to a file
</PRE>
<PRE> get and write allow abbreviated (uniquely) vector names or digits (1-Nvec)
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "data.html">data</A>, <A HREF = "dump.html">dump</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

55
doc/vec.txt Normal file
View File

@ -0,0 +1,55 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
vec tool :h3
[Purpose:]
Create numeric vectors from columns in file or list of vecs.
[Description:]
The vec tool creates numeric vectors that can be extracted, written to
files, or imported into other tools like "plotview"_plotview.html for
plotting.
The vec constructor takes either a file or list argument. For a file
argument, columns of numeric data are read from the file. Blank lines
or lines that do not start with a numeric character (0123456789.-) are
skipped. Each column must have the same number of values. For a list
argument, each element of the list is assumed to be a vector of values
(i.e. the list is a list of lists), as shown in the example below.
The columns of data may be accessed by number (1-N) or by name ("col1"
thru "colN").
The get() and write() methods extract the numeric vectors of data.
[Usage:]
v = vec("file1") read in numeric vectors from a file
v = vec(array) array = list of numeric vectors :pre
skip blank lines and lines that start with non-numeric characters
example array with 2 vecs = \[\[1,2,3,4,5\], \[10,20,30,40,50\]\]
assigns names = "col1", "col2", etc :pre
nvec = v.nvec # of vectors
nlen = v.nlen lengths of vectors
names = v.names list of vector names
x,y,... = l.get(1,"col2",...) return one or more vectors of values
l.write("file.txt") write all vectors to a file
l.write("file.txt","col1",7,...) write listed vectors to a file :pre
get and write allow abbreviated (uniquely) vector names or digits (1-Nvec) :pre
[Related tools:]
"data"_data.html, "dump"_dump.html
[Prerequisites:] none

60
doc/vmd.html Normal file
View File

@ -0,0 +1,60 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>vmd tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Control VMD from python.
</P>
<P><B>Description:</B>
</P>
<P>The vmd tool is a simple wrapper on the <A HREF = "http://www.ks.uiuc.edu/Research/vmd">VMD visualization
package</A>, a popular tool for visualizing snapshots from molecular
dynamics simulations.
</P>
<P>The vmd constructor invokes VMD in its own window. Data can be passed
to it for visualization via the new(), data(), replace(), and append()
methods. The other methods permit more specialized interactions with
VMD through its command syntax.
</P>
<P><B>Usage:</B>
</P>
<PRE>v = vmd() start up VMD
v.stop() shut down VMD instance
v.clear() delete all visualizations
</PRE>
<PRE>v.rep(style) set default representation style. One of
(Lines|VDW|Licorice|DynamicBonds|Points|CPK)
v.new(file[,type]) load new file (default file type 'lammpstrj')
v.data(file[,atomstyle]) load new data file (default atom style 'full')
v.replace(file[,type]) replace current frames with new file
v.append(file[,type]) append file to current frame(s)
v.set(snap,x,y,z,(True|False)) set coordinates from a pizza.py snapshot to new or current frame
</PRE>
<PRE>v.frame(frame) set current frame
v.flush() flush pending input to VMD and update GUI
v.read(file) read Tcl script file (e.g. saved state)
</PRE>
<PRE>v.enter() enter interactive shell
v.debug([True|False]) display generated VMD script commands?
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "gl.html">gl</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>Python pexpect package.
</P>
</HTML>

55
doc/vmd.txt Normal file
View File

@ -0,0 +1,55 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
vmd tool :h3
[Purpose:]
Control VMD from python.
[Description:]
The vmd tool is a simple wrapper on the "VMD visualization
package"_vmd, a popular tool for visualizing snapshots from molecular
dynamics simulations.
:link(vmd,http://www.ks.uiuc.edu/Research/vmd)
The vmd constructor invokes VMD in its own window. Data can be passed
to it for visualization via the new(), data(), replace(), and append()
methods. The other methods permit more specialized interactions with
VMD through its command syntax.
[Usage:]
v = vmd() start up VMD
v.stop() shut down VMD instance
v.clear() delete all visualizations :pre
v.rep(style) set default representation style. One of
(Lines|VDW|Licorice|DynamicBonds|Points|CPK)
v.new(file\[,type\]) load new file (default file type 'lammpstrj')
v.data(file\[,atomstyle\]) load new data file (default atom style 'full')
v.replace(file\[,type\]) replace current frames with new file
v.append(file\[,type\]) append file to current frame(s)
v.set(snap,x,y,z,(True|False)) set coordinates from a pizza.py snapshot to new or current frame :pre
v.frame(frame) set current frame
v.flush() flush pending input to VMD and update GUI
v.read(file) read Tcl script file (e.g. saved state) :pre
v.enter() enter interactive shell
v.debug(\[True|False\]) display generated VMD script commands? :pre
[Related tools:]
"gl"_gl.html
[Prerequisites:]
Python pexpect package.

54
doc/vtk.html Normal file
View File

@ -0,0 +1,54 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>vtk tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Convert LAMMPS snapshots to VTK format.
</P>
<P><B>Description:</B>
</P>
<P>The vtk tool converts atom snapshots in a LAMMPS dump or data file to
the VTK format used by various visualization packages.
</P>
<P>The vtk constructor takes an object that stores atom snapshots
(<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>) as its first argument. The atom
snapshots must have "id", "type", "x", "y", and "z" defined; see the
map() methods of those tools.
</P>
<P>The one(), many(), and single() methods convert specific snapshots to
the VTK format and write them out. Optionally, a file prefix for the
XYZ output files can also be specified. A ".xyz" suffix will be
appended to all output files.
</P>
<P><B>Usage:</B>
</P>
<PRE>v = vtk(d) d = object containing atom coords (dump, data)
</PRE>
<PRE>v.one() write all snapshots to tmp.vtk
v.one("new") write all snapshots to new.vtk
v.many() write snapshots to tmp0000.vtk, tmp0001.vtk, etc
v.many("new") write snapshots to new0000.vtk, new0001.vtk, etc
v.single(N) write snapshot for timestep N to tmp.vtk
v.single(N,"file") write snapshot for timestep N to file.vtk
</PRE>
<PRE> surfaces in snapshot will be written to SURF1.vtk, SURF2.vtk, etc
where each surface (triangle type) is in a different file
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "cfg.html">cfg</A>, <A HREF = "data.html">data</A>, <A HREF = "dump.html">dump</A>,
<A HREF = "ensight.html">ensight</A>, <A HREF = "xyz.html">xyz</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

49
doc/vtk.txt Normal file
View File

@ -0,0 +1,49 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
vtk tool :h3
[Purpose:]
Convert LAMMPS snapshots to VTK format.
[Description:]
The vtk tool converts atom snapshots in a LAMMPS dump or data file to
the VTK format used by various visualization packages.
The vtk constructor takes an object that stores atom snapshots
("dump"_dump.html, "data"_data.html) as its first argument. The atom
snapshots must have "id", "type", "x", "y", and "z" defined; see the
map() methods of those tools.
The one(), many(), and single() methods convert specific snapshots to
the VTK format and write them out. Optionally, a file prefix for the
XYZ output files can also be specified. A ".xyz" suffix will be
appended to all output files.
[Usage:]
v = vtk(d) d = object containing atom coords (dump, data) :pre
v.one() write all snapshots to tmp.vtk
v.one("new") write all snapshots to new.vtk
v.many() write snapshots to tmp0000.vtk, tmp0001.vtk, etc
v.many("new") write snapshots to new0000.vtk, new0001.vtk, etc
v.single(N) write snapshot for timestep N to tmp.vtk
v.single(N,"file") write snapshot for timestep N to file.vtk :pre
surfaces in snapshot will be written to SURF1.vtk, SURF2.vtk, etc
where each surface (triangle type) is in a different file :pre
[Related tools:]
"cfg"_cfg.html, "data"_data.html, "dump"_dump.html,
"ensight"_ensight.html, "xyz"_xyz.html
[Prerequisites:] none

51
doc/xyz.html Normal file
View File

@ -0,0 +1,51 @@
<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A>
</CENTER>
<HR>
<H3>xyz tool
</H3>
<P><B>Purpose:</B>
</P>
<P>Convert LAMMPS snapshots to XYZ format.
</P>
<P><B>Description:</B>
</P>
<P>The xyz tool converts atom snapshots in a LAMMPS dump or data file to
the XYZ format used by various visualization packages.
</P>
<P>The xyz constructor takes an object that stores atom snapshots
(<A HREF = "dump.html">dump</A>, <A HREF = "data.html">data</A>) as its first argument. The atom
snapshots must have "id", "type", "x", "y", and "z" defined; see the
map() methods of those tools.
</P>
<P>The one(), many(), and single() methods convert specific snapshots to
the XYZ format and write them out. Optionally, a file prefix for the
XYZ output files can also be specified. A ".xyz" suffix will be
appended to all output files.
</P>
<P><B>Usage:</B>
</P>
<PRE>x = xyz(d) d = object containing atom coords (dump, data)
</PRE>
<PRE>x.one() write all snapshots to tmp.xyz
x.one("new") write all snapshots to new.xyz
x.many() write snapshots to tmp0000.xyz, tmp0001.xyz, etc
x.many("new") write snapshots to new0000.xyz, new0001.xyz, etc
x.single(N) write snapshot for timestep N to tmp.xyz
x.single(N,"file") write snapshot for timestep N to file.xyz
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "cfg.html">cfg</A>, <A HREF = "data.html">data</A>, <A HREF = "dump.html">dump</A>,
<A HREF = "ensight.html">ensight</A>, <A HREF = "vtk.html">vtk</A>
</P>
<P><B>Prerequisites:</B> none
</P>
</HTML>

46
doc/xyz.txt Normal file
View File

@ -0,0 +1,46 @@
"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(pd,Manual.html)
:link(pc,Section_tools.html)
:line
xyz tool :h3
[Purpose:]
Convert LAMMPS snapshots to XYZ format.
[Description:]
The xyz tool converts atom snapshots in a LAMMPS dump or data file to
the XYZ format used by various visualization packages.
The xyz constructor takes an object that stores atom snapshots
("dump"_dump.html, "data"_data.html) as its first argument. The atom
snapshots must have "id", "type", "x", "y", and "z" defined; see the
map() methods of those tools.
The one(), many(), and single() methods convert specific snapshots to
the XYZ format and write them out. Optionally, a file prefix for the
XYZ output files can also be specified. A ".xyz" suffix will be
appended to all output files.
[Usage:]
x = xyz(d) d = object containing atom coords (dump, data) :pre
x.one() write all snapshots to tmp.xyz
x.one("new") write all snapshots to new.xyz
x.many() write snapshots to tmp0000.xyz, tmp0001.xyz, etc
x.many("new") write snapshots to new0000.xyz, new0001.xyz, etc
x.single(N) write snapshot for timestep N to tmp.xyz
x.single(N,"file") write snapshot for timestep N to file.xyz :pre
[Related tools:]
"cfg"_cfg.html, "data"_data.html, "dump"_dump.html,
"ensight"_ensight.html, "vtk"_vtk.html
[Prerequisites:] none

21
examples/README Normal file
View File

@ -0,0 +1,21 @@
This directory contains a collection of example scripts. There is one
test_*.py script for each tool in Pizza.py. These illustrate how to
use the tool. The small data sets used by these scripts are in the
files sub-directly.
A test_*.py script can be run by launching Pizza.py from this
directory, e.g.
% pizza.py -f test_animate.py from the shell
> @run test_animtate.py from Pizza.py
The other scripts in this directory perform specific tasks. Read the
comments at the top of the script file for an explanation. Most of
these scripts require a data set to operate on, which is not provided.
These scripts are included simply to illustrate how a particular task
can be done in Pizza.py.
These scripts create output and temporary files as they operate.
These are all named tmp*. Pizza.py does not clean up all the
temporary files, since they are sometimes useful to look at for
debugging or other purposes.

BIN
examples/files/bucky0000.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 223 KiB

BIN
examples/files/bucky0001.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 223 KiB

BIN
examples/files/bucky0002.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 227 KiB

BIN
examples/files/bucky0003.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 224 KiB

1530
examples/files/data.micelle Normal file
View File

File diff suppressed because it is too large Load Diff

1057
examples/files/data.rhodo Normal file
View File

File diff suppressed because it is too large Load Diff

2740
examples/files/dump.bond Normal file
View File

File diff suppressed because it is too large Load Diff

10018
examples/files/dump.kinase Normal file
View File

File diff suppressed because it is too large Load Diff

1417
examples/files/dump.lines Normal file
View File

File diff suppressed because it is too large Load Diff

6045
examples/files/dump.micelle Normal file
View File

File diff suppressed because it is too large Load Diff

22143
examples/files/dump.peptide Normal file
View File

File diff suppressed because it is too large Load Diff

5723
examples/files/dump.peptide.1 Normal file
View File

File diff suppressed because it is too large Load Diff

17091
examples/files/dump.peptide.2 Normal file
View File

File diff suppressed because it is too large Load Diff

2883
examples/files/dump.peptide.only Normal file
View File

File diff suppressed because it is too large Load Diff

5003
examples/files/image.svg Normal file
View File

File diff suppressed because it is too large Load Diff
Side by Side

After

Width:  |  Height:  |  Size: 552 KiB

184
examples/files/log.ccell Normal file
View File

@ -0,0 +1,184 @@
ChemCell (1 Nov 2004)
# Lotka-Volterra reactions
seed 3998694
volume 1.0e-11
species prey
species predator
species food
count prey 1000
count predator 1000
count food 1000
reaction 1 food prey 1.0e10 prey prey food
reaction 2 prey predator 1.0e10 predator predator
reaction 3 predator 1.0
stats 1.0
run_style gillespie
run 100.0
Domain:
global size in xyz = 0 0 0
Particles:
number of 3d species = 3
min/max 3d diffusivities = 0 0
number of 2d species = 0
initial particles = 0
Move:
Reactions:
number of 1-reactant reactions = 1
min/max 1-reactant rates = 1 1
number of 2-reactant reactions = 2
min/max 2-reactant rates = 1e+10 1e+10
min/max reaction distance = 0 0
max/min reaction probabilities = nan 0
Memory usage in Mbyte/proc (ave/max/min)
parts = 0 0 0
bins = 0 0 0
surfs = 0 0 0
total = 0 0 0
Step Time prey predator food
0 0 1000 1000 1000
4692 1.00009 597 1578 1000
7799 2.00172 310 1163 1000
9645 3.00015 338 776 1000
11461 4.00011 602 589 1000
14379 5.0001 965 857 1000
18851 6.00007 748 1454 1000
22512 7.00046 370 1255 1000
24955 8.00074 403 930 1000
27100 9 482 757 1000
29691 10.0001 761 794 1000
33309 11.0005 786 1155 1000
36960 12 504 1224 1000
39734 13.0004 496 965 1000
42491 14.0002 617 900 1000
45457 15.0004 702 953 1000
48965 16 634 1175 1000
52213 17 430 1065 1000
54659 18.0003 445 902 1000
57045 19.0009 631 778 1000
60145 20.0003 716 991 1000
63486 21.0001 588 1071 1000
66522 22.0003 591 1002 1000
69455 23.0001 605 981 1000
72394 24.0006 604 951 1000
75265 25.0013 659 934 1000
78598 26.0004 697 1050 1000
81666 27.0003 485 1061 1000
84221 28.0001 597 904 1000
87384 29.0006 727 1030 1000
90855 30 625 1066 1000
94074 31.0002 641 1118 1000
97342 32.0001 600 1082 1000
100200 33.0001 548 956 1000
102869 34.0002 543 904 1000
105514 35.0002 619 834 1000
108533 36.0005 651 1036 1000
111683 37.0004 610 1052 1000
114757 38.0012 470 1060 1000
117160 39.0017 412 879 1000
119493 40.0001 663 720 1000
122836 41.0001 843 1040 1000
126736 42 558 1256 1000
129669 43.0009 429 1038 1000
131998 44.0006 518 781 1000
134494 45.0006 715 762 1000
138030 46 713 1166 1000
141338 47.0002 496 1160 1000
143924 48.0004 366 931 1000
145935 49.0019 482 656 1000
148272 50.0001 868 685 1000
152460 51.0006 996 1287 1000
157045 52.0003 471 1487 1000
159549 53.0007 271 994 1000
161246 54.0001 405 613 1000
163326 55.0002 900 594 1000
168218 56.0002 1112 1485 1000
172925 57.0006 360 1642 1000
175150 58.0022 213 953 1000
176678 59 409 584 1000
178951 60.0002 893 631 1000
183064 61.0004 935 1288 1000
187196 62.0001 403 1454 1000
189482 63.0007 289 911 1000
191356 64.0014 494 634 1000
193721 65 897 670 1000
198165 66.0002 987 1395 1000
202535 67.0001 426 1495 1000
205000 68.0012 241 978 1000
206544 69.0007 348 591 1000
208490 70.0002 785 549 1000
212330 71.0001 1162 1160 1000
217128 72.0001 460 1597 1000
219694 73.0001 259 1005 1000
221459 74.0001 435 592 1000
223616 75.0001 814 602 1000
227560 76.0001 1127 1174 1000
232496 77.0006 451 1655 1000
235034 78.0002 252 1021 1000
236607 79.0003 352 568 1000
238504 80.0003 807 575 1000
242326 81.0001 1029 1097 1000
246831 82.0001 493 1513 1000
249606 83 295 1042 1000
251351 84.0003 414 631 1000
253495 85.0001 834 587 1000
257467 86 1158 1163 1000
262343 87.0003 444 1588 1000
264752 88.0001 250 1007 1000
266292 89.0003 343 583 1000
268051 90.0015 761 490 1000
271888 91 1238 1099 1000
277508 92.0002 487 1880 1000
280262 93 201 1063 1000
281699 94.0006 266 573 1000
283173 95.0004 612 432 1000
286341 96.0006 1320 867 1000
292092 97.0003 575 1928 1000
295174 98.0015 180 1211 1000
296648 99.0003 211 635 1000
297937 100.003 523 387 1000
Loop time of 2.9678 on 1 procs for 297937 steps
Move time (%) = 0 (0)
Migrt time (%) = 0 (0)
React time (%) = 0.996689 (33.5835)
RComm time (%) = 0 (0)
Outpt time (%) = 1.04967 (35.3688)
Balnc time (%) = 0 (0)
Other time (%) = 0.921435 (31.0478)
Nlocal: 0 ave 0 max 0 min
Histogram: 1 0 0 0 0 0 0 0 0 0
Nghost: 0 ave 0 max 0 min
Histogram: 1 0 0 0 0 0 0 0 0 0
Move statistics (total & per-step):
moves = 0 0
BC collide = 0 0
tri checks = 0 0
relect hits = 0 0
near hits = 0 0
stick hits = 0 0
far hits = 0 0
thru hits = 0 0
Reaction statistics (total & per-step):
overlaps = 0 0
reactions = 297937 1
count of each reaction: (1 98790) (2 99267) (3 99880)
Memory usage in Mbyte/proc (ave/max/min)
parts = 0 0 0
bins = 0 0 0
surfs = 0 0 0
total = 0 0 0
Equivalance map of species & type
map prey 1
map predator 2
map food 3

Some files were not shown because too many files have changed in this diff Show More