greenServeFE logogreenServeFELanguage, VM and Native Module Reference

Documentation home / Native modules / gs_chemistry

Native C module API · ABI version 1

gs_chemistry: Chemistry API

Complete source-grounded API reference for greenServeFE gs_chemistry: mole calculations, concentrations, acid-base chemistry, gas laws, stoichiometry, thermochemistry, kinetics and electrochemistry.

Module scope

Scalar chemistry calculations implemented in C, including amount of substance, solution concentration, acid/base logarithms, ideal gas relationships, balanced-equation ratios, reaction energy, first-order kinetics and the Nernst equation.

The module is a native C shared object. It adds an imported namespace to GSVE; it does not add keywords, alter the parser/compiler, or change the bytecode VM.

Contents

Build, install and import

Build the corresponding native module from the greenServeFE build repository using its matching manually triggered GitHub Actions workflow. The workflow's artifact is a build output; it is not automatically installed into every greenServeFE runtime.

# After placing the shared object in this directory:
export GREENSERVE_MODULE_PATH=/usr/local/lib/modules
export LD_LIBRARY_PATH=/usr/local/lib/modules:$LD_LIBRARY_PATH

# In a file named program.gsve:
import gs_chemistry;
print(gs_chemistry.info());

For a simple import, the VM searches the current directory, ./modules, the platform loader path, and directories listed in GREENSERVE_MODULE_PATH. The module must be named gs_chemistry.so in a searched location.

Exported API and signatures

ExportGSVE call signatureDescription
infogs_chemistry.info()Returns module name, version and scope.
constantsgs_chemistry.constants()R, Avogadro constant N_A, Faraday constant F, STP molar volume and pKw at 25 °C.
molesmoles(mass, molar_mass)Amount of substance = mass / molar mass; molar mass must be positive.
mass_from_molesmass_from_moles(moles, molar_mass)Mass = nM.
particles_from_molesparticles_from_moles(moles)Particle count = nN_A.
molaritymolarity(moles, volume)Molar concentration = moles / solution volume.
dilution_final_concentrationdilution(initial_concentration, initial_volume, final_volume)C₂ = C₁V₁/V₂.
mass_concentrationmass_concentration(mass, volume)Mass per volume.
molalitymolality(moles, solvent_mass)Moles per solvent mass; supply solvent mass in kg for mol/kg.
mole_fractionmole_fraction(component_moles, total_moles)Component amount / total amount; requires 0 ≤ component ≤ total.
ppmppm(solute, solution)Mass fraction × 10⁶; inputs must use the same mass unit.
phph(hydrogen_concentration)−log₁₀[H⁺]; concentration must be positive.
hydrogen_ion_concentrationhydrogen_ion_concentration(pH)10^(−pH).
pohpoh(hydroxide_concentration)−log₁₀[OH⁻]; concentration must be positive.
ph_from_pohph_from_poh(pOH)14 − pOH (25 °C water convention).
ideal_gas_volumeideal_gas_volume(moles, pressure, temperature)V = nRT/P; pressure and temperature must be positive.
ideal_gas_molesideal_gas_moles(pressure, volume, temperature)n = PV/RT; volume and temperature must be positive.
boyle_volumeboyle_volume(P1, V1, P2)V₂ = P₁V₁/P₂; P₂ must be positive.
charles_volumecharles_volume(V1, T1, T2)V₂ = V₁T₂/T₁; temperatures must be positive.
combined_gas_volumecombined_gas_volume(P1, V1, T1, P2, T2)V₂ = P₁V₁T₂/(T₁P₂); pressures and temperatures must be positive.
stoichiometric_product_molesstoichiometric_product_moles(reactant_moles, reactant_coefficient, product_coefficient)Theoretical product moles from balanced-equation coefficients.
percent_yieldpercent_yield(actual, theoretical)100 × actual / theoretical; theoretical amount must be positive.
reaction_heatreaction_heat(moles, enthalpy)q = nΔH.
gibbs_free_energygibbs_free_energy(enthalpy, entropy, temperature)ΔG = ΔH − TΔS; use consistent energy units.
first_order_half_lifefirst_order_half_life(initial, rate_constant)The source accepts two numbers but calculates ln(2)/k; the first argument is currently unused.
first_order_remainingfirst_order_remaining(initial, rate_constant, time)N(t) = N₀e^(−kt).
arrhenius_rate_constantarrhenius_rate_constant(A, activation_energy, temperature)k = A exp(−Ea/RT); activation energy and R must share units.
mass_percentmass_percent(solute_mass, solution_mass)100 × solute mass / total solution mass.
stp_gas_volume_litersstp_gas_volume_liters(moles)n × 22.414 L using the module's STP convention.
nernst_potentialnernst_potential(E0, temperature, electron_count, reaction_quotient)E = E⁰ − RT/(nF) ln Q; n and Q must be positive.

Constants and conventions

constants() returns R = 8.31446261815324, N_A = 6.02214076×10²³, F = 96485.33212, molar_volume_STP_L = 22.414 and pKw_at_25C = 14. The module's STP gas-volume helper uses 22.414 liters per mole.

Use SI-compatible units consistently: pressure in pascals with volume in cubic meters for the ideal gas law, temperature in kelvin, and energy/entropy units that agree in the Gibbs and Arrhenius equations. For molality, pass solvent mass in kilograms to obtain mol/kg.

The source implementation of first_order_half_life(initial, rate_constant) currently does not use its first argument; the result is ln(2)/k. This documentation preserves the actual two-argument export signature rather than presenting a guessed one-argument overload.

Practical GSVE examples

These examples use the implemented GSVE syntax: define declarations, func functions, semicolon-terminated statements, arrays, objects, for value in array iteration, and member calls.

import gs_chemistry;

define c = gs_chemistry.constants();
print(c.R);
print(c.N_A);

define sample_mass = 10;
define molar_mass = 58.44;
define amount = gs_chemistry.moles(sample_mass, molar_mass);
print(amount);

define solution_molarity = gs_chemistry.molarity(amount, 0.5);
print(solution_molarity);

define diluted = gs_chemistry.dilution_final_concentration(2, 0.1, 0.5);
print(diluted);

define ph_value = gs_chemistry.ph(0.000001);
define h_concentration = gs_chemistry.hydrogen_ion_concentration(6);
print(ph_value);
print(h_concentration);

define gas_volume = gs_chemistry.ideal_gas_volume(1, 101325, 273.15);
print(gas_volume);

define product_moles = gs_chemistry.stoichiometric_product_moles(2, 2, 1);
print(product_moles);

define remaining = gs_chemistry.first_order_remaining(100, 0.2, 5);
print(remaining);

define electrode = gs_chemistry.nernst_potential(1.1, 298.15, 2, 1);
print(electrode);

Validation, limits and numerical behavior

Native module functions validate their inputs and return GSVE null for invalid types, missing required numeric arguments, non-finite values, invalid domains, or resource-limit violations. Check inputs before using results in subsequent calculations.

VM and runtime relationship

GSVE source passes through the lexer, parser/AST, bytecode compiler and VM. Imported module functions are native function values stored in the module object. Calls such as gs_chemistry.info() are ordinary GSVE member access and function-call expressions; the VM dispatches them through the native function interface. Arrays and objects passed to native functions are GSVE runtime values, not C pointers exposed to the script.

Use greenServeFE --dump program.gsve to inspect compiled bytecode, greenServeFE --trace program.gsve to trace VM execution, and greenServeFE --profile program.gsve to collect opcode and function profiling data. These options inspect VM execution; they do not profile individual C instructions inside this module.

Related references