trajectorydata package¶
Top-level package for TrajectoryData.
Summary¶
Exceptions:
TrajectoryParserError |
Exception raised if a TrajectoryData file is malformed |
Classes:
TrajectoryData |
Tabular data of expectation values for one or more trajectories. |
Reference¶
-
exception
trajectorydata.
TrajectoryParserError
[source]¶ Bases:
Exception
Exception raised if a
TrajectoryData
file is malformed
-
class
trajectorydata.
TrajectoryData
(ID, dt, seed, n_trajectories, data)[source]¶ Bases:
object
Tabular data of expectation values for one or more trajectories. Multiple TrajectoryData objects can be combined with the
extend()
method, in order to accumulate averages over an arbitrary number o trajectories. As much as possible, it is checked that all trajectories are statistically independent. A record is kept to ensure exact reproducibility.Parameters: - ID (str) – A unique, RFC 4122 compliant identifier (as generated by
new_id()
) - dt (float) – Time step between data points (>0)
- seed (int) – The random number generator seed on which the data is based
- n_trajectories (int) – The number of trajectories from which the data is averaged (It is assumed that the random number generator was seeded with the given seed, and then the given number of trajectories were calculated sequentially)
- data (dict of str to tuple of arrays) – dictionary (preferably
OrderedDict) of expectation value data. The value of
data[operator_name]
must be a tuple of four numpy arrays (real part of expectation value, imaginary part of expectation value, real part of standard deviation, imaginary part of standard deviation). The operator names must contain only ASCII characters and must be shorter thancol_width - 10
.
Raises: ValueError
– if ID is not RFC 4122 compliant, dt is an invalid or non-positive float, or data does not follow the correct structure.Attributes: - ID (str) – A unique ID for the current state of the TrajectoryData
(read-only). See
ID
property. - table (OrderedDict of str to numpy array) – A table that contains four
column for every known operator (real/imaginary part of the
expectation value, real/imaginary part of the variance). Note that
the table attribute can easily be converted to a
pandas.DataFrame
(DataFrame(data=traj.table)
). The table attribute should be considered read-only. - dt (float) – Time step between data points
- nt (int) – Number of time steps / data points
- operators (list of str) – An iterator of the operator names. The column names in the table attribute derive from these. Assuming “X” is one of the operator names, there will be four keys in table: “Re[<X>]”, “Im[<X>]”, “Re[var(X)]”, “Im[var(X)]”
- record (OrderedDic of str to tuple of int, int, list) – A copy of the
complete record of how the averaged expectation values for all
operators were obtained. See discussion of the
record
property. - col_width (int) – width of the data columns when writing out data.
Defaults to 25 (allowing to full double precision). Note that
operator names may be at most of length
col_width-10
-
col_width
= 25¶
-
classmethod
read
(filename)[source]¶ Read in TrajectoryData from the given filename. The file must be in the format generated by the write method.
Raises: TrajectoryParserError
– if the file has an incorrect format
-
classmethod
from_qsd_data
(operators, seed, workdir='.')[source]¶ Instantiate from one or more QSD output files specified as values of the dictionary operators
Each QSD output file must have the following structure:
- The first line must start with the string “Number_of_Trajectories”, followed by an integer (separated by whitespace)
- All following lines must contain five floating point numbers (time, real/imaginary part of expectation value, and real/imaginary part of variance), separated by whitespace.
All QSD output files must contain the same number of lines, specify the same number of trajectories, and use the same time grid values (first column). It is the user’s responsibility to ensure that all out output files were indeed generated in a single QSD run using the specified initial seed for the random number generator.
Parameters: - operators (dict of str to str) – dictionary (preferably OrderedDict) of operator name to filename. The filenames are relative to the workdir. Each filename must contain data in the format described above
- seed (int) – The seed to the random number generator that was used to produce the data file
- workdir (str) – directory to which the filenames in operators are relative to
Raises: ValueError
– if any of the data files do not have the correct format or are inconsistentNote
Remember that is is vitally important that all quantum trajectories that go into an average are statistically independent. The
TrajectoryData
class tries as much as possible to ensure this, by refusing to combine identical IDs, or trajectories originating from the same seed. To this end, in thefrom_qsd_data()
method, the ID of the instantiated object will depend uniquely on the collective data read from the QSD output files.
-
classmethod
new_id
(name=None)[source]¶ Generate a new unique identifier, as a string. The identifier will be RFC 4122 compliant. If name is None, the resulting ID will be random. Otherwise, name must be a string that the ID will depend on. That is, calling new_id repeatedly with the same name will result in identical IDs.
-
ID
¶ A unique RFC 4122 compliant identifier. The identifier changes whenever the class data is modified (via the
extend()
method). Two instances of TrajectoryData with the same ID are assumed to be identical
-
record
¶ A copy of the full trajectory record, i.e., a history of calls to the
extend()
method. Its purpose is to ensure that the data is completely reproducible. This entails storing the seed to the random number generator for all sets of trajectories.The record is an OrderedDict that maps the original ID of any TrajectoryData instance combined via
extend()
to a tuple(seed, n_trajectories, ops)
, whereseed
is the seed to the random number generator that was used to calculate a specific set of trajectories (sequentially),n_trajectories
are the number of trajectories in that dataset, andops
is a list of operator names for which expectation values were calculated. This may be the complete list of operators in the operators attribute, or a subset of those operators (Not all trajectories have to include data for all operators).For example, let’s assume we have a
QSDCodeGen
instance to set up for a QSD propagation. Two observables ‘X1’, ‘X2’, have been added to be written to file ‘X1.out’, and ‘X2.out’. Theset_trajectories()
method has been called withn_trajectories=10
, after which a call torun()
with argumentseed=SEED1
, performed a sequential propagation of 10 trajectories, with the averaged expectation values written to the output files.This data may now be read into a new TrajectoryData instance
traj
via thefrom_qsd_data()
class method (with seed=SEED1). The newly created instance (with, let’s say,ID='8d102e4b-...'
) will have one entry in its record:'8d102e4b-...': (SEED1, 10, ['X1', 'X2'])
Now, let’s say we add a new observable ‘A2’ (output file ‘A2.out’) for the
QSDCodeGen
instance (in addition to the existing observables X1, X2), and call therun()
method again, with a new seedSEED2
. We then updatetraj
with a call such as:traj.extend(TrajectoryData.from_qsd_data( {'X1':'X1.out', 'X2':'X2.out', 'A2':'A2.out'}, SEED2)
The record will now have an additional entry, e.g.:
'd9831647-...': (SEED2, 10, ['X1', 'X2', 'A2'])
traj.table
will contain the averaged expectation values (average over 20 trajectories for ‘X1’, ‘X2’, and 10 trajectories for ‘A2’). The record tells use that to reproduce this table, 10 sequential trajectories starting fromSEED1
must be performed for X1, X2, followed by another 10 trajectories for X1, X2, A2 starting fromSEED2
.
-
operators
¶ Iterator over all operators
-
record_IDs
¶ Set of all IDs in the record
-
dt
¶ Time step between data points
-
nt
¶ Number of time steps / data points
-
shape
¶ Tuple
(n_row, n_cols)
for the data in self.table. The time grid is included in the column count
-
record_seeds
¶ Set of all random number generator seeds in the record
-
tgrid
¶ Time grid, as numpy array
-
to_str
(show_rows=-1)[source]¶ Generate full string representation of the TrajectoryData
Parameters: show_rows (int) – If given > 0, maximum number of data rows to show. If there are more rows, they will be indicated by an ellipsis ( ...
)Raises: ValueError
– if any operator name is too long to generate a label that fits in the limit given by thecol_width
class attribute
-
write
(filename)[source]¶ Write data to a text file. The TrajectoryData may later be restored by the read class method from the same file
-
extend
(*others, **kwargs)[source]¶ Extend data with data from one or more other TrajectoryData instances, averaging the expectation values. Equivalently to
traj1.extend(traj2)
, the syntaxtraj1 += traj2
may be used.Raises: ValueError
– if data in self and and any element of others are incompatibleTypeError
– if any others are not an instance of TrajectoryData
- ID (str) – A unique, RFC 4122 compliant identifier (as generated by