Working with Containers

The following examples use these Substances:

salt = Substance.solid(name='NaCl', mol_weight=58.44)
water = Substance.liquid(name='H2O', mol_weight=18.01528, density=1.0)
sodium_sulfate = Substance.solid(name='sodium_sulfate', mol_weight=142.04)
triethylamine = Substance.liquid(name='triethylamine', mol_weight=101.19, density=0.726)

Creating solutions

Create a 1 M solution of salt water:

salt_water = Container.create_solution(solute=salt, solvent=water, concentration='1 mol/L', total_quantity='100 mL')

If a name is not specified, a name is generated from the solute and solvent names.

Two out of the three parameters concentration, quantity, and total_quantity must be specified. The third is calculated from the other two.

A solution can be made of more than one solute at the same time:

solution = Container.create_solution(solute=[salt, sodium_sulfate], solvent=water, concentration='1 M', total_quantity='100 mL')

This will have 1 M of each solute in the solution.

If one value for a parameter is given, it is assumed to be the same for all solutes. If multiple values are given, they must be the same length as the number of solutes.

You can specify separate concentrations for each solute as well:

solution = Container.create_solution(solute=[salt, sodium_sulfate], solvent=water, concentration=['1 M', '0.5 M'], total_quantity='100 mL')

Or, you can specify how much of each solute you want:

solution = Container.create_solution(solute=[salt, sodium_sulfate], solvent=water, quantity=['50 mg', '50 mg'], total_quantity='100 mL')

Getting properties

You can get the instructions for preparing a Container:

>>> print(salt_water.instructions)
Add 5.844 g of NaCl, 94.156 mL of H2O to a container.

You can get the current concentration of a Container with respect to a solute:

>>> print(salt_water.get_concentration(solute=salt, units='M'))
1.0

You can get the current volume of a Container:

>>> print(salt_water.get_volume(unit='mL'))
100.0

Note

All Containers are immutable. Any operations on a Container will return a new, modified Container object.

Diluting solutions

Using the result of the previous example, we can dilute the solution to 0.5 M:

salt_water = salt_water.dilute(solute=salt, solvent=water, concentration='0.5 M')

>>> print(salt_water.instructions)
Add 5.844 g of NaCl, 94.156 mL of H2O to a container.
Dilute with 100.0 mL of H2O.

>>> print(salt_water.get_volume(unit='mL'))
200.0

>>> print(salt_water.get_concentration(solute=salt, units='M'))
0.5

Filling Containers

We can fill the salt_water Container from the previous example to a total volume of 400 mL:

salt_water = salt_water.fill_to(solvent=water, quantity='400 mL')

>>> print(salt_water.instructions)
Add 5.844 g of NaCl, 94.156 mL of H2O to a container.
Dilute with 100.0 mL of H2O.
Fill with 200.0 mL of H2O.

>>> print(salt_water.get_concentration(solute=salt, units='M'))
0.25

Transferring Between Containers

You can transfer a volume of a solution to another container:

new_container = Container(name='new container')
salt_water = Container.create_solution('salt water', solute=salt, solvent=water,
                                       concentration='1 M', total_quantity='100 mL')

salt_water, new_container = Container.transfer(source=salt_water, destination=new_container, quantity='10 mL')

The depleted source container and the new container are returned (as Containers are immutable, copies are returned).

>>> salt_water.get_volume(unit='mL')
90.0

>>> print(new_container.get_volume(unit='mL'))
10.0

Diluting Stock Solutions

In the previous examples, we made a solution by dissolving a solid into a liquid. You can also create a solution by diluting part of a stock solution:

salt_water1M = Container.create_solution(name='salt water (1 M)', solute=salt, solvent=water, concentration='1 M', quantity='100 mL')

salt_water1M, salt_water500mM = Container.create_solution_from(name='salt water (0.5 M)', source=salt_water1M, solute=salt,
                                                               solvent=water, concentration='0.5 M', quantity='10 mL')

This requests the dilution of salt_water1M with water.
The target concentration of salt in the new solution is 0.5 M.
This requests the diluted solution have a volume of 10 mL.
This sets the name of the new solution to 'salt water (0.5 M)'.
Some, but not necessarily all, of the source solution salt_water1M is used (here only 5 mL is used).
The depleted salt_water1M and the new diluted solution salt_water500mM are returned.
If the desired concentration is not possible, a ValueError is raised.

>>> print(salt_water500mM.instructions)
Add 5.0 mL of H2O to 5.0 mL of salt water (1 M).

95 mL of the 1 M salt water solution remains.

>>> print(salt_water1M.get_volume(unit='mL'))
95.0

Using a solution as the solvent

Previously, we used a pure liquid as the solvent. You can also use a solution as the solvent.
Specifically, the solvent in create_solution_from can be a Container, which may contain the solute.

Create the solvent solution:

sodium_sulfate1M = Container.create_solution(name='sodium sulfate 1 M', solute=sodium_sulfate, solvent=triethylamine,
                                             concentration='1 M', total_quantity='100 mL')

Note

Sodium sulfate is not really soluble in triethylamine. This is just an example.

Use sodium_sulfate1M and salt_water1M from above to create a 0.5 M salt solution:

salt_water1M, sodium_sulfate1M, mixture = Container.create_solution_from(name='mixture', source=salt_water1M, solute=salt,
                                                                         solvent=sodium_sulfate1M, concentration='0.5 M', quantity='10 mL')

The remainder of the source solution, the remainder of the solvent solution, and the new solution are returned in that order.

>>> print(mixture.instructions)
Add 5.0 mL of sodium sulfate (1 M) to 5.0 mL of salt water (1 M).

>>> print(salt_water1M.get_volume(unit='mL'))
95.0

>>> print(sodium_sulfate1M.get_volume(unit='mL'))
95.0