README.md 9.56 KB
Newer Older
1
SWIFT: SPH WIth Fine-grained inter-dependent Tasking
Josh Borrow's avatar
Josh Borrow committed
2 3
====================================================

Josh Borrow's avatar
Josh Borrow committed
4 5
[![Build Status](https://gitlab.cosma.dur.ac.uk/jenkins/job/GNU%20SWIFT%20build/badge/icon)](https://gitlab.cosma.dur.ac.uk/jenkins/job/GNU%20SWIFT%20build/)

6 7 8 9 10 11 12
SWIFT is a gravity and SPH solver designed to run cosmological simulations
on peta-scale machines, scaling well up to 10's of thousands of compute
node.

More general information about SWIFT is available on the project
[webpages](http://www.swiftsim.com).

Josh Borrow's avatar
Josh Borrow committed
13 14 15 16
For information on how to _run_ SWIFT, please consult the onboarding guide
available [here](http://www.swiftsim.com/onboarding.pdf). This includes
dependencies, and a few examples to get you going.

17 18 19 20
We suggest that you use the latest release branch of SWIFT, rather than the
current master branch as this will change rapidly. We do, however, like to
ensure that the master branch will build and run.

21 22 23
This GitHub repository is designed to be an issue tracker, and a space for
the public to submit patches through pull requests. It is synchronised with
the main development repository that is available on the
Josh Borrow's avatar
Josh Borrow committed
24 25 26
[ICC](http://icc.dur.ac.uk)'s GitLab server which is available
[here](https://gitlab.cosma.dur.ac.uk/swift/swiftsim).

27
Please feel free to submit issues to this repository, or even pull
28
requests. We will try to deal with them as soon as possible, but as the
29
core development team is quite small this could take some time.
Josh Borrow's avatar
Josh Borrow committed
30

31 32 33 34 35
Disclaimer
----------

We would like to emphasise that SWIFT comes without any warranty of accuracy,
correctness or efficiency. As mentioned in the license, the software comes
36
`as-is` and the onus is on the user to get meaningful results. Whilst the
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
authors will endeavour to answer questions related to using the code, we
recommend users build and maintain their own copies. This documentation contains
the most basic information to get started. Reading it and possibly also the
source code is the best way to start running simulations.

The users are responsible to understand what the code is doing and for the
results of their simulation runs.

Note also that the values of the parameters given in the examples are only
indicative. We recommend users experiment by themselves and a campaign of
experimentation with various values is highly encouraged. Each problem will
likely require different values and the sensitivity to the details of the
physical model is something left to the users to explore.

Acknowledgment & Citation
-------------------------

In order to keep track of usage and measure the impact of the software, we
kindly ask users publishing scientific results using SWIFT to add the following
sentence to the acknowledgment section of their papers:

"The research in this paper made use of the SWIFT open-source
simulation code (http://www.swiftsim.com, Schaller et al. 2018)
version X.Y.Z."

with the version number set to the version used for the simulations and the
reference pointing to the ASCL entry of the code: https://ascl.net/1805.020.



Josh Borrow's avatar
Josh Borrow committed
67 68 69
Contribution Guidelines
-----------------------

70
The SWIFT source code uses a variation of the 'Google' formatting style.
71
The script 'format.sh' in the root directory applies the clang-format-10
72 73
tool with our style choices to all the SWIFT C source file. Please apply
the formatting script to the files before submitting a pull request.
74 75 76 77 78 79 80

Please check that the test suite still runs with your changes applied before
submitting a pull request and add relevant unit tests probing the correctness
of new modules. An example of how to add a test to the suite can be found by
considering the tests/testGreeting case.

Any contributions that fail any of the automated tests will not be accepted.
81 82
Contributions that include tests of the proposed modules (or any current ones!)
are highly encouraged.
Josh Borrow's avatar
Josh Borrow committed
83

84 85 86
Runtime parameters
------------------

Josh Borrow's avatar
Josh Borrow committed
87 88 89 90
```
 Welcome to the cosmological hydrodynamical code
    ______       _________________
   / ___/ |     / /  _/ ___/_  __/
91 92 93
   \__ \| | /| / // // /_   / /
  ___/ /| |/ |/ // // __/  / /
 /____/ |__/|__/___/_/    /_/
Josh Borrow's avatar
Josh Borrow committed
94 95
 SPH With Inter-dependent Fine-grained Tasking

96
 Version : 0.8.5
Josh Borrow's avatar
Josh Borrow committed
97 98 99 100 101
 Website: www.swiftsim.com
 Twitter: @SwiftSimulation

See INSTALL.swift for install instructions.

102 103 104 105 106 107 108 109 110 111
Usage: swift [options] [[--] param-file]
   or: swift [options] param-file
   or: swift_mpi [options] [[--] param-file]
   or: swift_mpi [options] param-file

Parameters:

    -h, --help                        show this help message and exit

  Simulation options:
112

113
    -b, --feedback                    Run with stars feedback.
114
    -c, --cosmology                   Run with cosmological time integration.
115
    --temperature                     Run with temperature calculation.
116
    -C, --cooling                     Run with cooling (also switches on --temperature).
117 118 119
    -D, --drift-all                   Always drift all particles even the ones
                                      far from active particles. This emulates
                                      Gadget-[23] and GIZMO's default behaviours.
120
    -F, --star-formation              Run with star formation.
121 122 123
    -g, --external-gravity            Run with an external gravitational potential.
    -G, --self-gravity                Run with self-gravity.
    -M, --multipole-reconstruction    Reconstruct the multipoles every time-step.
124
    -s, --hydro                       Run with hydrodynamics.
125
    -S, --stars                       Run with stars.
126
    -B, --black-holes                 Run with black holes.
127
    -k, --sinks                       Run with sink particles.
128 129
    -u, --fof                         Run Friends-of-Friends algorithm to
                                      perform black hole seeding.
130
    -x, --velociraptor                Run with structure finding.
131
    --line-of-sight                   Run with line-of-sight outputs.
132
    --limiter                         Run with time-step limiter.
133 134
    --sync                            Run with time-step synchronization
                                      of particles hit by feedback events.
135 136 137
    --logger                          Run with the particle logger.
    -R, --radiation                   Run with radiative transfer. Work in
                                      progress, currently has no effect.
138

139 140
  Simulation meta-options:

141 142 143
    --quick-lyman-alpha               Run with all the options needed for the
                                      quick Lyman-alpha model. This is equivalent
                                      to --hydro --self-gravity --stars --star-formation
144
                                      --cooling.
145 146 147 148 149 150 151 152 153 154
    --eagle                           Run with all the options needed for the
                                      EAGLE model. This is equivalent to --hydro
                                      --limiter --sync --self-gravity --stars
                                      --star-formation --cooling --feedback
                                      --black-holes --fof.
    --gear                            Run with all the options needed for the
                                      GEAR model. This is equivalent to --hydro
                                      --limiter --sync --self-gravity --stars
                                      --star-formation --cooling --feedback.

155
  Control options:
156

157
    -a, --pin                         Pin runners using processor affinity.
158 159 160 161 162 163 164 165 166 167 168 169 170
    -d, --dry-run                     Dry run. Read the parameter file, allocates
                                      memory but does not read the particles
                                      from ICs. Exits before the start of time
                                      integration. Checks the validity of
                                      parameters and IC files as well as memory
                                      limits.
    -e, --fpe                         Enable floating-point exceptions (debugging
                                      mode).
    -f, --cpu-frequency=<str>         Overwrite the CPU frequency (Hz) to be
                                      used for time measurements.
    -n, --steps=<int>                 Execute a fixed number of time steps.
                                      When unset use the time_end parameter
                                      to stop.
171 172
    -o, --output-params=<str>         Generate a parameter file with the options
                                      for selecting the output fields.
173
    -P, --param=<str>                 Set parameter value, overiding the value
174 175 176 177 178 179 180 181
                                      read from the parameter file. Can be used
                                      more than once {sec:par:value}.
    -r, --restart                     Continue using restart files.
    -t, --threads=<int>               The number of threads to use on each MPI
                                      rank. Defaults to 1 if not specified.
    -T, --timers=<int>                Print timers every time-step.
    -v, --verbose=<int>               Run in verbose mode, in MPI mode 2 outputs
                                      from all ranks.
182 183 184 185
    -y, --task-dumps=<int>            Time-step frequency at which task graphs
                                      are dumped.
    --cell-dumps=<int>                Time-step frequency at which cell graphs
                                      are dumped.
186 187
    -Y, --threadpool-dumps=<int>      Time-step frequency at which threadpool
                                      tasks are dumped.
188 189 190
    --dump-tasks-threshold=<flt>      Fraction of the total step's time spent
                                      in a task to trigger a dump of the task plot
                                      on this step
Josh Borrow's avatar
Josh Borrow committed
191

192
See the file examples/parameter_example.yml for an example of parameter file.
193
```