greenServeFE logogreenServeFELanguage, VM and Native Module Reference

Documentation home / Native modules / gs_physics

Native C module API · ABI version 1

gs_physics: Classical Physics API

Complete source-grounded API reference for greenServeFE gs_physics: kinematics, Newtonian mechanics, energy, fluids, thermodynamics, waves, gravitation and ideal-gas calculations.

Module scope

A collection of scalar physics formulas implemented in C. The functions accept finite numeric GSVE arguments and return numeric values or null when validation fails. SI units are recommended unless a function explicitly specifies degrees or Kelvin.

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_physics;
print(gs_physics.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_physics.so in a searched location.

Exported API and signatures

ExportGSVE call signatureDescription
infogs_physics.info()Returns module name, version and scope metadata.
constantsgs_physics.constants()Returns SI/scientific constants: G, c, g_standard, R, k_B and N_A.
velocityvelocity(distance, time)Average velocity; distance / time.
accelerationacceleration(initial_velocity, final_velocity, time)Average acceleration; (final − initial) / time.
displacementdisplacement(initial_velocity, time, acceleration)s = ut + ½at².
final_velocityfinal_velocity(initial_velocity, acceleration, displacement)Returns the non-negative square root of u² + 2as.
forceforce(mass, acceleration)Newton's second law, F = ma.
momentummomentum(mass, velocity)Linear momentum, p = mv.
impulseimpulse(force, time)Constant-force impulse, J = FΔt.
kinetic_energykinetic_energy(mass, velocity)Kinetic energy, ½mv²; mass must be non-negative.
potential_energypotential_energy(mass, g, height)Gravitational potential energy, mgh; mass must be non-negative.
workwork(force, distance, angle_degrees)Work, Fd cos θ; angle is in degrees.
powerpower(work, time)Average power, work / time.
pressurepressure(force, area)Pressure, force / area; area must be positive.
densitydensity(mass, volume)Density, mass / volume; volume must be positive.
hydrostatic_pressurehydrostatic_pressure(fluid_density, g, depth)Gauge pressure ρgh; density and depth must be non-negative.
buoyant_forcebuoyant_force(fluid_density, g, displaced_volume)Buoyant force ρgV; density and displaced volume must be non-negative.
centripetal_forcecentripetal_force(mass, speed)Centripetal expression m v²; this export does not take radius.
spring_forcespring_force(spring_constant, displacement)Hooke's law restoring force −kx.
spring_energyspring_energy(k, x)Elastic potential energy ½kx².
heatheat(mass, specific_heat, delta_T)Sensible heat Q = mcΔT.
latent_heatlatent_heat(mass, latent_heat)Phase-change energy Q = mL.
efficiency_percentefficiency_percent(output, input)Efficiency percentage 100 × output / input; input must be positive.
wave_speedwave_speed(frequency, wavelength)Wave speed v = fλ.
thermal_expansion_lengththermal_expansion_length(length, coefficient, delta_T)Returns L(1 + αΔT), the expanded length.
carnot_efficiency_percentcarnot_efficiency_percent(cold_temperature, hot_temperature)Ideal Carnot efficiency 100(1 − Tc/Th); temperatures must be Kelvin.
frequencyfrequency(period)Frequency 1/T; period must be positive.
pendulum_periodpendulum_period(length, g)Small-angle simple pendulum period 2π√(L/g).
gravitational_forcegravitational_force(mass1, mass2, distance)Newtonian attraction Gm₁m₂/r²; distance must be positive.
orbital_speedorbital_speed(central_mass, radius)Circular orbital speed √(GM/r).
escape_speedescape_speed(central_mass, radius)Escape speed √(2GM/r).
ideal_gas_pressureideal_gas_pressure(moles, volume, temperature)Ideal gas pressure nRT/V; volume and temperature must be positive.
doppler_frequencydoppler_frequency(source_frequency, observer_velocity, source_velocity, wave_speed)Classical Doppler relation f(v + vs)/(v − vo), with speed and velocity-domain checks.
reynolds_numberreynolds_number(density, velocity, characteristic_length)Returns ρvL (the source implementation does not divide by dynamic viscosity).

Physical quantities and units

Use a consistent unit system. The gravitational constant and gas constant in constants() use SI values. The work angle is the one explicit degree-based input. Thermodynamic temperatures used in Carnot and ideal-gas formulas should be absolute Kelvin values.

Important implementation detail: centripetal_force(mass, speed) returns m·v² and does not accept radius; reynolds_number(density, velocity, characteristic_length) returns ρvL and does not include viscosity. These exports are exactly as implemented and should not be mistaken for the complete textbook formulas.

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_physics;

define constants = gs_physics.constants();
print(constants.g_standard);
print(constants.G);

define distance = 120;
define elapsed = 8;
define v = gs_physics.velocity(distance, elapsed);
print(v);

define a = gs_physics.acceleration(4, 20, 4);
define f = gs_physics.force(3, a);
print(f);

define kinetic = gs_physics.kinetic_energy(2, v);
define work_done = gs_physics.work(10, 5, 60);
print(kinetic);
print(work_done);

define pressure = gs_physics.pressure(100, 2);
define density = gs_physics.density(12, 3);
print(pressure);
print(density);

define orbit = gs_physics.orbital_speed(5.972e24, 6.371e6);
define escape = gs_physics.escape_speed(5.972e24, 6.371e6);
print(orbit);
print(escape);

define results = [v, a, f, kinetic, work_done, pressure, density];
for value in results {
    print(value);
}

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_physics.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