# RWSims

Collection of rw sim scripts

## Usage 

```python
# the next lines are only necessary if the python script is not in the same folder as rwsims
import sys
sys.path.append('/path/to/RWSims')

from rwsims.sims import run_ste_sim, run_spectrum_sim

run_ste_sim('/path/to/json-file')
run_spectrum_sim('/path/to/json-file')
```

## Parameter file

Parameter for a simulation are given by a JSON file, sections are:

### simulation

| key  | type            | description                            |
|------|-----------------|----------------------------------------|
| num  | integer         | Number of trajectories                 |
| seed | integer or null | Seed value for random number generator | 

### molecule

| key   | type  | description        |
|-------|-------|--------------------|
| delta | float | Anisotropy (in Hz) |
| eta   | float | Asymmetry          |

### correlation_times

| key             | type       | description                                                               |
|-----------------|------------|---------------------------------------------------------------------------|
| distribution    | string     | Name of distribution. Possible values: `DeltaDistribution`, `LogGaussian` |
| tau             | _variable_ | Characteristic time of distribution (in s)                                |
| Other parameter | _variable_ | Additional parameter, e.g., sigma                                         |
  
### motion

| key             | type       | description                                                      |
|-----------------|------------|------------------------------------------------------------------|
| model           | string     | Name of motion. Possible values: `RandomJump`, `TetrahedralJump` |


### spectrum

| key             | type       | description                                       |
|-----------------|------------|---------------------------------------------------|
| dwell_time      | float      | Dwell time of acquisition (in s)                  |
| num_points      | integer    | Number of acquisition points                      |
| t_echo          | _variable_ | One or more echo delays (use zero for FID) (in s) |
| line_broadening | float      | Additional exponential broadening (in Hz)         |
| t_pulse         | float      | Pulse length used of attenuation (in s)           |

### ste

| key             | type       | description                                     |
|-----------------|------------|-------------------------------------------------|
| t_evo           | _variable_ | One or more evolution times                     |
| t_mix           | _variable_ | One or more mixing times                        |
| t_echo          | float      | Optional echo delay for 4-pulse sequence (in s) |

### _variable_ type

Keys of type _variable_ can be a single value, a list of values, or values between a given start and stop value.

Examples:

+ A single value 

```json
{
  // Other parameter...
  "tau": 1e-3,
  // More parameter..
}
```

+ A list of predefined values, defined by key `list`
```json
{
  // Other parameter...
  "tau": {
    "list": [1e-5, 1e-4, 1e-3, 1e-2]
  },
  // More parameter..
}
```

++ A list of predefined values, based on start and end value
```json
{
  // Other parameter...
  "tau": {
    "start": 1e-6,
    "stop": 1e0,
    "steps": 31,
    "is_log": true  // this parameter is optional, default is false
  },
  // More parameter..
}
```

## Output

Results are written to text files and png images.
+ For spectrum simulations:
  1. Each combination of distribution and motion parameter produces files for the dependence of timesignals/spectra on the echo delay.
  2. The reduction factor vs. correlation time is plotted for all variable together in one png plot
+ For STE simulation:
  1. Each combination of distribution and motion parameter produces files for the CC/SS decays.
  2. The dependence on the evolution of the fit parameter is saved and plotted for the various variable combinations