# 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 than col_width - 10. ValueError – if ID is not RFC 4122 compliant, dt is an invalid or non-positive float, or data does not follow the correct structure. 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[]”, “Im[]”, “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
copy()[source]

Return a (deep) copy of the current object

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 ValueError – if any of the data files do not have the correct format or are inconsistent

Note

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 the from_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), where seed 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, and ops 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’. The set_trajectories() method has been called with n_trajectories=10, after which a call to run() with argument seed=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 the from_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 the run() method again, with a new seed SEED2. We then update traj 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 from SEED1 must be performed for X1, X2, followed by another 10 trajectories for X1, X2, A2 starting from SEED2.

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 (...) ValueError – if any operator name is too long to generate a label that fits in the limit given by the col_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

n_trajectories(operator)[source]

Return the total number of trajectories for the given operator

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 syntax traj1 += traj2 may be used.

Raises: ValueError – if data in self and and any element of others are incompatible TypeError – if any others are not an instance of TrajectoryData