Python API documentation

This section contains API documentation of the cython/python part of Code_TYMPAN, extracted from the docstrings embedded in the code.

Code_TYMPAN: acoustic simulations based on C++ libraries

Allows to:

  • Build a project from a XML file describing an industrial site

  • Compute and export the altimetry from the topography and infrastructures of the site

  • Create an abstract model from the “business” description, describing the topography as a mesh, and with elementary sources and receptors

  • Run an acoustic simulation on an abstract model

  • Update the business model with the results of the altimetry computation or with the result of the acoustic computation

Here goes an example of the typical use that can be done of this API:

# Build a project from a site XML description (update site infrastructure altimetry)
project = Project.from_xml("my_project.xml")
# Build a simplified model from the project (the new infrastructure
# altitudes will be taken into account)
model = Model.from_project(project)
# Load and configure the acoustic solver
solver = Solver.from_project(project)
# Run the simulation
result = solver.solve(model)
# Update the project with the results of the computation
project.import_result(model, result)

This API can be used to do other types of computations, here goes an example of how to do a computation with user-defined sources:

# Build a project from a XML model
project = Project.from_xml("my_project.xml")
# build solver model, but don't use the project sources
model = Model.from_project(project, set_sources=False)
# Manually define the sources (position and spectrum) depending on your needs
model.add_source(Source((0, 0, 0), np.array([100.0] * 31, dtype=float)))
model.add_source(Source((100, 50, 0), np.array([150.0] * 31, dtype=float)))
solver = Solver.from_project(project)
result = solver.solve(model)
# retrieve combined spectra per receptor
combined_spectra = result.combined_spectra()

Acoustic solver

Business project

class tympan.models.project.Project(project)

Acoustic project describing an industrial site

add_computation(current=True)

Add a new empty computation to the project, set it as the default computation if current is True and return it

property computations

Project computations

property current_computation

Project current computation

export_altimetry(output_fpath, size_criterion=0.0, refine_mesh=True, use_vol_landtakes=False)

Write site altimetry mesh to output_fpath (ply format)

classmethod from_xml(fpath, verbose=False, update_altimetry=True, size_criterion=0.0, refine_mesh=True, use_vol_landtakes=False)

Create a project from fpath XML file path, on the way update project site infrastructure altimetry if update_altimetry is True

get_altimetered_area()

Return the altimetered area computed on altimetry mesh

import_result(model, solver_result)

Update project’s site acoustic according to solver result

select_computation(computation)

Set project current computation to computation (computation MUST be part of project’ computations)

set_solver(solvername, computation=None, solverdir=None)

Set solver solvername to computation computation

solverdir is the directory where one can find the solver library. If None, it will

be retrieved from “TYMPAN_SOLVERDIR” environment variable, which must be defined. if computation is None, the solver will be set to the current computation of the project

property site

Project site

to_xml(filepath)

Export the project to a filepath XML file

update_site_altimetry(verbose=False, size_criterion=0.0, refine_mesh=True, use_vol_landtakes=False)

Update the altitude of the site infrastructure items

Site infrastructure items whose altitude can be updated are machines, buildings, sources, receptors, etc.

Model and solver

class tympan.models.solver.Model

Model describing a site made of a mesh, sources, and receptors

Used for acoustic simulation.

add_source(source)

Add an acoustic source to the model.

export_triangular_mesh()

Build a triangular mesh from the acoustic problem model

Return two nparrays:

  • ‘nodes’: an array of nodes (of dimension ‘npoints’X3), where each line stands for a node and contains 3 coordinates)

  • ‘triangles’: an array of triangles (of dimension ‘ntriangles’X3), where each line stands for a triangle and contains the indices of its 3 vertices in the ‘nodes’ array.

classmethod from_project(project, set_sources=True, set_receptors=True)

Create a solver model from a project

node_coords(idx)

Return a tuple with the 3D coordinates for the node of id ‘idx’

property nreceptors

Return the number of acoustic receptors involved in the model

property nsources

Return the number of acoustic sources involved in the model

property receptors

Acoustic receptors of the model

property sources

Acoustic sources of the model

property triangles

Acoustic triangles of the model

class tympan.models.solver.Receptor(position)

An acoustic receptor.

positiontuple

(x, y, z) coordinates

property spectrum

Acoustic power spectrum of this Receptor.

class tympan.models.solver.Solver(solver)

Acoustic solver

classmethod from_name(name, parameters_file, solverdir=None, verbose=False)

Return an instance of solver with name.

name can be “default” or “Anime3D” for instance.

classmethod from_project(project, solverdir=None, verbose=False)

Load and configure solver

‘solverdir’ is the directory where one can find the solver library. If None, it will be retrieved from “TYMPAN_SOLVERDIR” environment variable, which must be defined. The configuration is read from the project.

solve(model)

Solve the acoustic problem described in the model (run a computation)

class tympan.models.solver.Source(position, spectrum, directivity=None)

An acoustic source.

positiontuple

(x, y, z) coordinates

spectrumSpectrum

acoustic power spectrum

shiftint, optional

the number of the first frequence for which a DB value is given (frequences start at 16 Hz and end at 16000Hz, 31 values in total)

directivity: Directivity, optional

source directivity

tympan.models.solver.fetch_solverdir()

Try to retrieve solver plugins directory from ‘TYMPAN_SOLVERDIR’ environment variable

If the environment variable is not defines, raise a RuntimeError.

Altimetry

This package provides altimetry computation from Topography and Infrastructures.

It relies on :

It is devided in several modules:

  • The datamodel module provides a representation for the geometrical feature of a Code_TYMPAN site

  • The merge module provides for merging subsite and cleaning out-of-bounds elements

  • The mesh modules provide for building a constrained triangulation for a single-node (i.e. already merged) site

  • The builder module chain operation from all modules to actually build the altimetry from the topography.

  • The visu provides visualtisation utilities mainly aimed as diagnostic helpers

class tympan.altimetry.AltimetryMesh(site, mesh, feature_by_face)

Holds a merged SiteNode and a mesh (i.e. faces and nodes)

builder = <module 'tympan.altimetry.builder' from '/home/docs/checkouts/readthedocs.org/user_builds/codetympan/checkouts/latest/python/tympan/altimetry/builder.py'>
classmethod from_site(site, use_vol_landtakes=False, **kwargs)

Build an altimetry mesh from a tympan Site.

Extra keyword arguments are passed to the mesh builder (see tympan.altimetry.builder.build_altimetry).

property material_by_face

Return a material_by_face mapping

to_ply(fpath)

Export mesh content to ‘fpath’ (PLY format)

Datamodel

Data model for the computation of the altimetry.

The input classes implement the geo_interface protocol which enable them to be used directly with Shapely and allow to easily load test data from a GeoJSON file.

exception tympan.altimetry.datamodel.InconsistentGeometricModel(message, ids=None, witness_point=None, names=None, **kwargs)
class tympan.altimetry.datamodel.SiteLandtake(coords, altitude, close_it=False, **kwargs)

When the main site landtake is considered as a level curve

tympan.altimetry.datamodel.load_csv_road(road_file_path)

Return a list of road profiles from a CSV road file

Builder

Provide chaining of the step required to build the altimetry of a compound site.

tympan.altimetry.builder.build_altimetry(mainsite, allow_features_outside_mainsite=False, size_criterion=0.0, refine_mesh=True)

Return the results of altimetry building from a site tree model.

tympan.altimetry.builder.material_by_face(feature_by_face)

Return a material_by_face mapping given a feature_by_face mapping

Merge

Merging sub-sites for the computation of the altimetry.

The main entry point is the function recursively_merge_all_subsites. It uses the class SiteNodeGeometryCleaner to perform a recursive merge of all the site note of a compound site to build a single site.

class tympan.altimetry.merge.SiteNodeGeometryCleaner(sitenode)

Clean a sitenode geometry, subsites excluded and build reports.

More precisely this class is build from a root SiteNode. Then the process_* method walk through the geometrical elements (level curves, material areas, landtakes, …) and associate them with a geometry we are sure to be within the site landtake and outside the landtake of any subsite.

The level curves are cut and the polygonal features are filtered according to the following policy:

  • the IDs of feature overlapping the boundary of the site node are reported in the erroneous_overlap list attributes

  • the IDs of feature entirely out of the site node are reported in the ignored_feature list attributes

The new geometry computed for each feature is available through the geom dictionary attribute, which is indexed by the feature IDs.

An equivalent site is maintained with the original features. The class also implement a __getitem__ method so that both the new geometry and the original properties can be accessed with geom, info = cleaner[feature_id].

check_issues_with_material_area_order()

Diagnostic helper: returns violation of the ordering for material area

import_cleaned_geometries_from(othercleaner)

Create new geometry and info into the site of this cleaner representing the cleaned geometry for each feature of the other cleaner.

Info are shared between the self and the other cleaner.

insert_position_for_sorted_material_area(inserted_area)

Insert the ID of inserted_area into _sorted_material_areas so that area appear most inner first.

Return its position in _sorted_material_areas.

The invariant is that for each pair of areas in the list at position i and j with i<j, either A(i) and A(J) are disjoint or A(i) is included in A(j).

merge_subsite(subsite)

Merge the cleaned geometries for subsite into the self cleaner

merged_site()

Return the merged site

tympan.altimetry.merge.recursively_merge_all_subsites(rootsite, allow_outside=True)

Merges all subsites and their subsites and so on into this merger.

Mesh

Provide triangulation and meshing of a clean, single site, geometry.

class tympan.altimetry.mesh.ElevationProfile(mesh, segment)

2D profile built from the intersection of a segment with a mesh CDT.

mesh: a ReferenceElevationMesh segment: a LineString (shapely.geometry)

Example:

>>> profile = ElevationProfile(mesh, ((0, 0), (1, 1)))
>>> # Evaluate the profile a distance 0.5 from segment origin.
>>> profile(0.5)
>>> # Evaluate the profile for an array of distances.
>>> h = profile(np.arange(0, 1, 0.1))
>>> # Compute the first and second derivative of the profile.
>>> dh = h.gradient()
>>> d2h = dh.gradient()
property direction

Direction vector (in horizontal plane) of the profile as a numpy array.

face_data_interpolator(face_data)

Return an interpolator on profile points for data associated with mesh faces through the face_data dict.

point_altitude(dist)

Return the altitude of a point located at dist from segment origin. This is the altitude of the mesh triangle the point belongs to.

point_data(dist, face_data, default=None)

Return some “data” at a point located at dist from segment origin based on the mesh face the point belongs to and the face_data mapping which relates mesh face handles to these “data”. default is used if the face is not found in the face_data map or the the point if outside the mesh convex hull. In case the point is located on a mesh vertex, the data of any of the mesh faces which the vertex belongs to will be used.

For instance, given a material_by_face map:

material = profile.point_data(dist, material_by_face)

will return the material of a point located at dist from segment origin in the profile.

point_data_interpolator(point_data, _distances=None)

Return an interpolator on profile points for data associated with profile points through point_data.

point_data may be a sequence of same lenght that distances or a callable giving data as a function of the distance to the segment origin.

property spline

The underlying interpolating spline.

May be None if the segment does not intersect the mesh.