Skip to content

SWIFTsim
SWIFTsim

Multiple materials and planetary equations of state

Last edited by Jacob Kegerreis
Page history

(( A big update is in progress so some of this info is outdated. Check back soon! ))

To allow different SPH particles to have different equations of state (EOS), as well as the addition of more complex EOS like iron and rock for planetary simulations such as giant impacts.

Also serves as a quick guide to implementing any new hydro scheme or new EOS.

See examples/UranusImpact/ for an example simulation with multiple materials. See tests/testEOS for testing and plotting the EOS.

Status

  • Implemented general EOS and "Minimal Multi Mat" hydro structure
  • Added Tillotson EOS
  • Added Hubbard & MacFarlane (1980) EOS
  • Added SESAME EOS
  • (WIP) Added "Density-Energy" hydro scheme to be an improved "Minimal Multi Mat"

Hydro Scheme

Create the Minimal Multi Mat hydro scheme; a copy of Minimal with added bits to allow multiple materials.

New Scheme

  • Create src/hydro/MinimalMultiMat/, starting with a copy of Minimal/.
  • src/hydro/MinimalMultiMat/*.h: Rename the header include guards appropriately.
  • configure.ac: Add the new --with-hydro option minimal-multi-mat like the existing ones.
  • src/debug.c, src/hydro.h, src/hydro_io.h, src/part.h: Similarly add like the other hydro schemes.

Multiple Materials

Add a new integer flag particle property to identify the material of every particle:

  • src/hydro/MinimalMultiMat/hydro_part.h: add material_id mat_id; to the part struct, where enum material_id is defined in src/equation_of_state/planetary/equation_of_state.h (see below).
  • src/hydro/MinimalMultiMat/hydro_debug.h: Add the p->mat_id integer to hydro_debug_particle().
  • src/hydro/MinimalMultiMat/hydro_io.h: Add mat_id to hydro_read_particles() and hydro_write_particles().

Use the material ID flag with the EOS:

  • src/hydro/MinimalMultiMat/hydro.h: Add p->mat_id as a third argument (after e.g. density and u) to all the EOS functions.

Equations of State

Add the planetary equation of state option, to contain a variety of EOS types, each with a variety of materials.

New EOS

  • Create src/equation_of_state/planetary/, starting with a copy of ideal_gas/.
  • configure.ac: Add the new --with-equation-of-state option planetary like the existing ones.
  • src/equation_of_state.h: Simlarly, add like the other EOS options.
  • src/equation_of_state/planetary/equation_of_state.h: Modify the header include guard, eos_print(), and eos_print_snapshot() appropriately.

Use the material ID flag with the EOS:

  • src/equation_of_state/planetary/equation_of_state.h: Add p->mat_id as a third argument (after e.g. density and u) to all the EOS functions (see above).

Multiple Materials

Each EOS type has its functions defined in its own header file, as well as the different parameters for each material of that type. The main planetary header then uses switch statements with a particle's mat_id to choose which specific EOS function to use.

In each EOS type's header, e.g. Tillotson in src/equation_of_state/planetary/tillotson.h:

  • Define struct Til_params to contain all the relevant material parameters for the EOS, such as characteristic energies or table parameters.
  • Define a function to set these parameters' values for each specific material, e.g. INLINE static void set_Til_iron(struct Til_params *mat, int mat_id) for Tillotson iron. This also sets the material ID when the function is called by eos_init() (see below).
  • Similarly, define a function to convert the parameter values into internal units, e.g. INLINE static void convert_units_Til(struct Til_params *mat, const struct unit_system* us)
  • Now define the actual EOS functions, one for each in the main equation_of_state.h. Add a prefix to the name, e.g. Til_ for Tillotson. Instead of taking the mat_id flag as the third argument, take (a pointer to) the actual material parameter struct, e.g. INLINE static float Til_internal_energy_from_entropy(float density, float entropy, struct Til_params *mat).
  • Some EOS do not support all of the functions, e.g. Tillotson does not include entropy, so must be used with an appropriate hydro scheme. Set these functions to raise an error. gas_entropy_from_internal_energy() is always called at setup and for snapshots, so should just return zero if it is not in this EOS.

In src/equation_of_state/planetary/equation_of_state.h:

  • eos_parameters: Declare the parameter structures for each material of each EOS type, e.g. struct Til_params Til_iron;.
  • enum type_id with type_factor: Assign a base ID for each EOS type.
  • enum material_id: Lists the material ID flags, using the base type value with an extra unit addition for each material of every EOS type, e.g. id_Til_iron = type_Til*type_factor + 1.
  • eos_init(): Call the functions to set the parameter values for each material of each EOS type and convert them to the internal units, e.g. set_Til_iron(&e->Til_iron, id_Til_iron); and convert_units_Til(&e->Til_iron, us);.
  • In each EOS function, use switch ((int) (mat_id / type_factor)) to select the base EOS type of the material using its mat_id.
  • For this EOS type, e.g. case type_Til:, declare a material parameter struct (pointer) of the relevant type, e.g. struct Til_params *mat_Til;, then use switch(mat_id) to select and point to the right material. e.g. case id_Til_iron: mat_Til = &eos.Til_iron;.
  • Call the EOS function, passing the input arguments and the material pointer, e.g. u = Til_internal_energy_from_entropy(density, entropy, mat_Til);, and return the value.

Input parameters

  • eos_init(): Read in things like table file names from the input parameters. To more neatly deal with defaults etc., first check the flag parameters e.g. use_Til to decide which EOS to initialise.

To Do

  • Add more equations of state (most of which will be read from tables).
  • Integrate with more/all hydro schemes
  • (Not any time soon) Try SPH-modifying schemes to improve interactions of different-material particles.