API guide

In this page a summary of all the functions and classes of the pypH library is given as a general reference.

`pypH.acid` module

class pypH.acid.Acid(pka, concentration, names=None)

The Acid class encodes the behavior of a generic mono or polyprotic acid. The number of acidic protons is defined automatically by setting the pKa values. The class can be used to compute the concentration of each deprotonated species at a given pH by directly calling its concentration method. Furthermore the class provides a simple interface to the construction of auxiliary curves by providing direct access to the deprotonated Species generated by the acid. These can be easily obtained using the () round bracket operator and specifying the deprotonation index

Parameters:

pka (List[float]) – The list of pka values associated to the various acid dissociations.
concentration (float) – The molar concentration of the acid.
names (Optional[List[str]]) – An optional field in which the user can specify names to be assigned to each deprotonation product. If no name is given the system will automatically call the species with the scheme H_iX^{{n-i}-}” where `X is a progressive letter assigned starting form A.

concentration(index, pH)

Compute the concentration of the user defined deprotonation state of the acid at the specified pH.

Parameters:

index (int) – The index of the deprotonation state as the number of lost protons
pH (float) – The pH value at which the concentration must be computed

Raises:

ValueError – Exceprion raised when the user specified index is smaller than zero or greate than the number of protons

Returns:

The concentration of the selected deprotonation state at the given pH.

Return type:

float

dilute(dilution_ratio, keep_id=False)

Generates a new Acid object with a concentration lower than the starting one by a factor equal to dilution_ratio.

Parameters:

dilution_ratio (float) – The dilution ratio to be applied.
keep_id (bool) – If set to True will set the ID of the diluted acid to the same value of the undiluted one.

Returns:

The acid object with the new reduced concentration.

Return type:

Acid

property id: int

The univocal ID that can be used to identiy the Acid.

Reutrns

int: The ID of the acid.

property names: List[str]

The names associated to each deprotonation product.

Returns:: The list of names.
Return type:: str

property nprotons: int

The number of acidic protons in the molecule

Returns:: The number of acidic protons
Return type:: int

class pypH.acid.AcidSpecies(acid_id, name, index)

Simple class used in the definition of an auxiliary curve to indentify a generic deprotonated species. The class can be directly used to construct Auxiliary class object by summation and subtraction with other Species or Auxiliary objects and multiplication by a float numerical coefficient.

Attribues

acid_id: int: The ID of the acid from which the speces is derived
name: str: The name of the selected species
index: int: The deprotonation index of the desired form.

Parameters:

acid_id (int)
name (str)
index (int)

`pypH.spectator` module

class pypH.spectator.Spectator(name, concentration)

The Spectator class encodes a generic spectator species with no acid-base properties.

Parameters:

name (str) – The name of the spectator species. (Accepts LaTeX)
concentration (float) – The molar concentration of the species.

property concentration: float

The concentration of the spectator species.

Returns:: The float indicating the concentration of the spectator species in mol/L.
Return type:: str

dilute(dilution_ratio, keep_id=False)

Generates a new Spectator object with a concentration lower than the starting one by a factor equal to dilution_ratio.

Parameters:

dilution_ratio (float) – The dilution ratio to be applied.
keep_id (bool) – If set to True will set the ID of the diluted spectator to the same value of the undiluted one.

Returns:

The spectator object with the new reduced concentration.

Return type:

Spectator

property id: int

The univocal ID that can be used to identiy the Spectator species.

Reutrns

int: The ID of the spectator species

property name: str

The name of the spectator species.

Returns:: The string containing the name of the spectator species.
Return type:: str

class pypH.spectator.SpectatorSpecies(spectator_id, name)

Simple class used in the definition of an auxiliary curve to indentify a generic spectator species. The class can be directly used to construct Auxiliary class object by summation and subtraction with other Species or Auxiliary objects and multiplication by a float numerical coefficient.

Attribues

spectator_id: int: The ID of the acid from which the speces is derived
name: str: The name of the selected species
index: int: The deprotonation index of the desired form.

Parameters:

spectator_id (int)
name (str)

`pypH.species` module

class pypH.species.Auxiliary

The Auxiliary class provides a simple object capable of handling the definition of auxiliary curves to be represented on the logarithmic diagram. The class provides an __iter__ method yielding ordered couples of species and coefficients. The class supports summations and subtraction with other Auxiliary and AcidSpecies class objects and multiplication by a float numerical value.

species

A list of the species involved in the curve definition

Type:: List[AcidSpecies]

coefficients

A list of the coefficients associated to the species list.

Type:: List[float]

class pypH.species.Species(name)

Abstract base class from which all the core-specific speces will be derived by inheritance.

Attribues

name: str: The name of the species.

to_auxiliary()

Function dedicated to the direct conversion of a Species object into an Auxiliary one.

Returns:: The auxiliary object encoding the species with coefficient 1.
Return type:: Auxiliary

Parameters:: name (str)

`pypH.system` module

class pypH.system.System

A simple class dedicated to the plot and manipulation of logarithmic diagrams. The class allows the user to define a system of acid and plot the concentration of the various deprotonation products as a function of the pH. The class also allows the user to define auxiliary curves to solve specific problems (e.g. solution based on protonic balance)

add(element)

Funtion used to add an acid species to the list of acids.

Parameters:: element (Union[Acid, Spectator) – The Acid or Spectator class enconding the properties and concentration of the species.
Raises:: TypeError – Exception raised if the element argument is not of Acid nor Spectator type.
Return type:: None

add_auxiliary(auxiliary, name=None, color=None)

Function used to add an auxiliary curve to the plot.

Parameters:

auxiliary (Auxiliary) – The pypH.species.Auxiliary object defining the curve to be plotted
name (Optional[str]) – The name of the auxiliary curve. If set to None the name will be set to aux. <N> with <N> a progressive number starting from 1.
color (Optional[str]) – The color to be used in tracing the auxiliary curve. If set to None (default) will leave the choice to matplotlib color sequence.

Raises:

TypeError – Exception raised if the auxiliary expression is not an Auxiliary type object.
RuntimeError – Exception raised if the deprotonation index of the Species is not compatible with the selected acid or if the acid ID does not match one of the acid in the system.

dilute(dilution_ratio)

The function generates a new System in which a global dilution has been applied to all the species. Please notiche that the resulting System object will keep the ID of all the original species.

Parameters:: dilution_ratio (float) – The dilution ratio to be applied.
Returns:: The system object with the new reduced concentrations.
Return type:: System

plot_logarithmic_diagram(pH_range=[0, 14], pH_delta=0.001, concentration_range=[1e-14, 1], show_legend=False, legend_location='lower right', figsize=[10, 9], save_path=None)

Funtion to plot the logarithmic diagram of the defined acid-base system.

Parameters:

pH_range (List[float]) – The minimum and maximum value of pH to be plotted, (defaut: [0, 14])
pH_delta (float) – The pH steps used in plotting the diagram (defaut: 0.001)
concentration_range (List[float]) – The range of concentrations to be plotted on the Y axis (default: [1e-14, 1])
show_legend (bool) – If set to True will show the legend with the name of the traces (default: False)
legend_location (Union[int, str]) – The location of the legend as expressed bu matplotlib. (default: lower right)
figsize (Tuple[float]) – The tuple of float values setting the size of the figure.
save_path (Optional[str]) – The path of the file where to save the logarithmic diagram image. If set to None (default) will only display the result to the user without saving the plot.

Return type:

None

plot_titration_curve(protonic_balance, with_acid, solution_volume, titrant_concentration, delta_volume, use_dilution=True, total_titrant_volume=None, eabs=1e-06, figsize=[12, 9], save_path=None)

Plot the titration curve for the system. The function can be used to plot titration using both strong acid or bases. The titration type can be selected using the with_acid option (True for strong acid, False for strong base).

Parameters:

protonic_balance (Auxiliary) – The protonic balance of the initial solution. (without the titrant term)
with_acid (bool) – If set to True will simulate a titration with strong acid if set to False with a strong base.
solution_volume (float) – The total volume of the solution to be titrated in mL.
titrant_concentration (float) – The concentration of the titrant solution in mol/L.
delta_volume (float) – The size of the titrant volume steps used in the simulation.
use_dilution (bool) – If set to True (default) will consider the effect of dilution.
total_titrant_volume (Optional[float]) – If set to a value different from None sets the volume of titrant at which the titration is stopped.
eabs (float) – The maximum absolute error to be used in the numerical solution of the protonic balance. (default: 1e-6)
figsize (Tuple[float]) – The tuple of float values setting the size of the figure.
save_path (Optional[str]) – The path of the file where to save the titration diagram image. If set to None (default) will only display the result to the user without saving the plot.

Return type:

None

solve(first, second=None, pH_range=(0.0, 14.0), eabs=1e-06)

Numerically computes the pH at which the equality first == second is satisfied. The function uses the dicotomic method in the range pH_range to solve the proble iteratively until the absolute variation between the terms is smaller then eabs.

Parameters:

first (Auxiliary) – The expression for the left side of the equation
second (Optional[Auxiliary]) – The expression for the right side of the equation. If None the solver will compute first == 0..
pH_range (Tuple[float, float]) – The pH range in which the solution must be searched. (default: (0., 14.))
eabs (float) – The maximum absolute error between iteration points to stop the dicotomic search. (default: 1e-6)

Raises:

TypeError – Exception raised if the auxiliary expression is not an Auxiliary type object.
RuntimeError – Exception raised if the deprotonation index of the Species is not compatible with the selected acid or if the acid ID does not match one of the acid in the system.

Returns:

The pH value at which the equality is satisfied.

Return type:

float

API guide

pypH.acid module

Reutrns

Attribues

pypH.spectator module

Reutrns

Attribues

pypH.species module

Attribues

pypH.system module

`pypH.acid` module

`pypH.spectator` module

`pypH.species` module

`pypH.system` module