# Heat transfer
The heat transfer function is designed to simulate heat transfer between two objects. It takes the mass, temperature and specific heat capacity of the objects into account. *\*Note that later the list of factors being taken into account will be expanded.*
## Files related to the heat transfer function
The heat transfer function's main code is located in the `src/modules/heat_transfer.rs` source file. You can also find a unit test of the function at `tests/heat_transfer_simulation_test.rs`.
## Usage of the heat transfer function
### Parts of the heat transfer function
You can import these parts of the heat transfer function:
- `simulate_heat_transfer` — The function that does most of the work and processes the calculations
- `HeatTransferResult` — The part of the heat transfer function that gives you the ability to return specific values
- `Object` — The part of the heat transfer function that gives you the ability to create new objects
You can import all of those simply with:
```rs
use openphys::{simulate_heat_transfer, HeatTransferResult, Object};
```
### Returnable values from the heat transfer function
These are the returnable values from the `heat_transfer` function:
- `time_steps` — The current amount of time steps, counting from `0`
- `total_time` — The total amount of time elapsed since the start of the heat transfer
- `total_heat_transferred` — Total heat transferred between the two objects in *Jules*
- `final_temp_of_obj1` — The final temperature of `obj1`
- `final_temp_of_obj2` — The final temperature of `obj2`
Here's an example of how you could return one of these values:
```rs
println!("Total time: {:.2} seconds", result.total_time);
```
### Creating new objects
You can create new objects with `Object::new(mass, temperature, specific_heat_capacity)`.
- `mass` — The mass of the object in kilograms (*kg*)
- `temperature` — The temperature of the object in Kelvin (*K*)
- `specific_heat_capacity` — The amount of energy required to change the temperature of the object by 1K (*J/kg\*K*)
An example of a new object is:
```rs
let mut obj1 = Object::new(1.0, 273.15, 4186.0); // 1kg of water at its freezing point
```
The variable is mutable because the `simulate_heat_transfer` function changes the temperature of the objects (`obj1` in this case).
### Setting up some other variables
Before we can begin using the `simulate_heat_transfer` function we need to specify some variables.
- `time_step` — The frequency we want the `simulate_heat_transfer` to update the temperature of an objects (1 `time_step` = 1 second) - adjust based on the accuracy you want, the *recommended* value is `0.1`
- `equilibrium_threshold` — Once the difference between two objects' temperatures fall into this threshold, no further changes are made to the objects' temperatures, thus assuming balance between the two objects' temperatures - the temperature difference between the two objects doesn't have to be exactly 0, just low enough that they don't affect each other anymore - adjust based on the accuracy you want, the *recommended* value is *10^-6* but anything lower than *10^-2* will do
An example of specifying these two variable is:
```rs
let time_step = 0.1; // 0.1 seconds
let equilibrium_threshold = 1e-6; // 10^-6
```
### Using the `simulate_heat_transfer` function
We can pass the two objects and the other variables we made into the `simulate_heat_transfer` as parameters like this: `simulate_heat_transfer(&mut obj1, &mut obj2, time_step, equilibrium_threshold)`.
Here's an example of using the `simulate_heat_transfer` function with the variables we specified:
```rs
let result = simulate_heat_transfer(&mut obj1, &mut obj2, time_step, equilibrium_threshold);
```