MusicBox#

An atmospheric chemistry box model. Powered by MUSICA.

This package contains modules for handling various aspects of a music box, including species, products, reactants, reactions, and more.

acom_music_box.music_box module#

class acom_music_box.music_box.MusicBox(box_model_options=None, initial_conditions=None, evolving_conditions=None)#

Bases: object

Represents a box model with attributes such as box model options, species list, reaction list, initial conditions, evolving conditions, solver, and state.

Attributes:

box_model_options (BoxModelOptions): Options for the box model simulation. initial_conditions (Conditions): Initial conditions for the simulation. evolving_conditions (List[EvolvingConditions]): List of evolving conditions over time. solver: The solver used for the box model simulation. state: The current state of the box model simulation.

add_evolving_condition(time_point, conditions)#

Add an evolving condition at a specific time point.

Args:

time_point (float): The time point for the evolving condition [s]. conditions (Conditions): The associated conditions at the given time point.

loadJson(path_to_json)#

Reads and parses a JSON file and create a solver

Args:

path_to_json (str): The JSON path to the JSON file.

Returns:

None

Raises:

ValueError: If the JSON string cannot be parsed.

load_mechanism(mechanism, solver_type=<_SolverType.rosenbrock_standard_order: 2>)#

Creates a solver for the specified mechanism.

Args:

mechanism (Mechanism): The mechanism to be used for the solver.

solve(callback=None)#

Solves the box model simulation and optionally writes the output to a file.

This function runs the box model simulation using the current settings and conditions. If a path is provided, it writes the output of the simulation to the specified file.

Args:

callback (function, optional): A callback function that is called after each time step. Defaults to None. The callback will take the most recent results, the current time, conditions, and the total simulation time as arguments.

Returns:

list: A 2D list where each inner list represents the results of the simulation at a specific time step.

acom_music_box.conditions module#

class acom_music_box.conditions.Conditions(pressure=None, temperature=None, species_concentrations=None, rate_parameters=None)#

Bases: object

Represents conditions for a simulation with attributes such as pressure, temperature, species concentrations, and reaction rates.

Attributes:

pressure (float): The pressure of the conditions in atmospheres. temperature (float): The temperature of the conditions in Kelvin. species_concentrations (dict[str, float]): A dictionary of species concentrations. rate_parameters (dict[str, float]): A dictionary of user-specified reaction rate parameters.

classmethod from_config(path_to_json, json_object)#

Creates an instance of the class from a configuration JSON object.

This class method takes a path to a JSON file, a configuration JSON object, a species list, and a reaction list, and uses them to create a new instance of the class.

Args:

path_to_json (str): The path to the JSON file containing the initial conditions and settings. json_object (dict): The configuration JSON object containing the initial conditions and settings.

Returns:

object: An instance of the Conditions class with the settings from the configuration JSON object.

classmethod read_data_values_from_table(data_json, react_types=None)#

Reads data values from a CSV-type table expressed in JSON.

This class method takes a JSON element, reads two rows, and sets variable names and values to the header and value rows.

Example:

"data": [
    ["ENV.temperature [K]", "ENV.pressure [Pa]", "CONC.A [mol m-3]", "CONC.B [mol m-3]"],
    [200, 70000, 0.67, 2.3e-9]
]
Args:

data_json (object): JSON list of two lists. react_types = set of reaction types only to include, or None to include all.

Returns:

dict: A dictionary of initial data values.

classmethod read_initial_conditions_from_file(file_path, react_types=None, preserve_type=False)#

Reads initial user-defined rate parameters from a file.

This class method takes a file path and a ReactionList, reads the file, and sets the initial rate parameters based on the contents of the file.

Args:

file_path (str): The path to the file containing the initial rate parameters. react_types = set of reaction types only to include, or None to include all.

Returns:

dict: A dictionary of initial user-defined rate parameters.

classmethod retrieve_initial_conditions_from_JSON(path_to_json, json_object, reaction_types, preserve_type)#

Retrieves initial conditions from CSV file and JSON structures. If both are present, JSON values will override the CSV values.

This class method takes a path to a JSON file, a configuration JSON object, and a list of desired reaction types.

Args:

path_to_json (str): The path to the JSON file containing the initial conditions and settings. json_object (dict): The configuration JSON object containing the initial conditions and settings. reaction_types: Use set like {“ENV”} for environmental conditions {“CONC”} for species concentrations, {“EMIS”, “PHOTO”} for reaction rates. preserve_type: If True, keep the reaction type in the key name. If False, remove the reaction type from the key name.

Returns:

object: A dictionary of name:value pairs.

acom_music_box.evolving_conditions module#

class acom_music_box.evolving_conditions.EvolvingConditions(headers=None, times=None, conditions=None)#

Bases: object

Represents evolving conditions with attributes such as time and associated conditions.

Attributes:

time (List[float]): A list of time points. conditions (List[Conditions]): A list of associated conditions.

add_condition(time_point, conditions)#

Add an evolving condition at a specific time point. Keep the two lists sorted in order by time. New arrivals will probably come at the end of the list.

Args:

time_point (float): The time point for the evolving condition. conditions (Conditions): The associated conditions at the given time point.

static from_config(path_to_json, config_JSON)#

Creates an instance of the EvolvingConditions class from a configuration JSON object.

This class method takes a path to a JSON file, a configuration JSON object, a SpeciesList, and a ReactionList, and uses them to create a new instance of the EvolvingConditions class.

Args:

path_to_json (str): The path to the JSON file containing the initial conditions and settings. config_JSON (dict): The configuration JSON object containing the initial conditions and settings. species_list (SpeciesList): A SpeciesList containing the species involved in the simulation. reaction_list (ReactionList): A ReactionList containing the reactions involved in the simulation.

Returns:

EvolvingConditions: An instance of the EvolvingConditions class with the settings from the configuration JSON object.

read_conditions_from_file(file_path)#

Read conditions from a file and update the evolving conditions.

Args:

file_path (str): The path to the file containing conditions UI_JSON.

Returns:
set: the headers read from the CSV file;

used for warning about condition overrides

acom_music_box.data_output module#

class acom_music_box.data_output.DataOutput(df, args)#

Bases: object

A class to handle data output operations for a DataFrame, including converting to CSV or NetCDF formats with appended units for columns. Designed for environmental data with specific units and formats.

This class manages file paths, unit mappings, and data output formats based on the provided arguments, ensuring valid paths and creating necessary directories.

Attributes#

dfpandas.DataFrame

The DataFrame to be output.

argsargparse.Namespace

Command-line arguments or configurations specifying output options.

unit_mappingdict

A dictionary mapping specific columns to their respective units.

Examples#

>>> import pandas as pd
>>> from argparse import Namespace
>>> df = pd.DataFrame({
...     'ENV.temperature': [290, 295, 300],
...     'ENV.pressure': [101325, 100000, 98500],
...     'ENV.number_density_air': [102, 5096, 850960],
...     'time': [0, 1, 2]
... })
>>> args = Namespace(output='output.nc')
>>> data_output = DataOutput(df, args)
>>> data_output.output()
output()#

Main method to handle output based on the provided arguments.

acom_music_box.plot_output module#

class acom_music_box.plot_output.PlotOutput(df, args)#

Bases: object

A class to handle plotting operations for a DataFrame, including plotting species concentrations over time using matplotlib.

This class manages the plotting tool, species list, and data output formats based on the provided arguments, ensuring valid paths and creating necessary directories.

Attributes#

dfpandas.DataFrame

The DataFrame to be plotted.

argsargparse.Namespace

Command-line arguments or configurations specifying plot options.

species_listlist of lists

A list of lists, where each sublist contains species to be plotted in a separate window.

Examples#

>>> import pandas as pd
>>> from argparse import Namespace
>>> df = pd.DataFrame({
...     'time': [0, 1, 2],
...     'CONC.A.mol m-3': [1, 2, 3],
...     'CONC.B.mol m-3': [4, 5, 6],
...     'CONC.C.mol m-3': [7, 8, 9]
... })
>>> args = Namespace(plot=['CONC.A,CONC.B'], plot_tool='matplotlib')
>>> plot_output = PlotOutput(df, args)
>>> plot_output.plot()
plot()#

Plot the specified species using matplotlib.

acom_music_box.model_options module#

class acom_music_box.model_options.BoxModelOptions(chem_step_time=None, output_step_time=None, simulation_length=None, grid='box')#

Bases: object

Represents options for a box model simulation.

Attributes:

grid (str): The type of grid. Default is “box”. chemStepTime (float): Time step for chemical reactions in the simulation in seconds. outputStepTime (float): Time step for output data in the simulation in hours. simulationLength (float): Length of the simulation in hours.

classmethod from_config(config_JSON)#

Create a new instance of the BoxModelOptions class from a JSON object from a configuration JSON.

Args:

UI_JSON (dict): A JSON object representing box model options.

Returns:

BoxModelOptions: A new instance of the BoxModelOptions class.

acom_music_box.utils module#

acom_music_box.utils.calculate_air_density(temperature, pressure)#

Calculate the air density in moles m-3

Args:

temperature (float): The temperature in Kelvin. pressure (float): The pressure in Pascals.

Returns:

float: The air density in moles m-3

acom_music_box.utils.convert_concentration(data, key, temperature, pressure)#

Convert the concentration from the input data to moles per cubic meter. This function assumes you are passing data from a music box configuration.

Args:

data (dict): The input data. key (str): The key for the concentration in the input data. temperature (float): The temperature in Kelvin. pressure (float): The pressure in Pascals.

Returns:

float: The concentration in moles per cubic meter.

acom_music_box.utils.convert_from_number_density(data, output_unit, temperature, pressure)#

Convert from mol m-3 to some other units

Args:

data (float): The data to convert in mol m-3. output_unit (str): The output units temperature (float): The temperature in Kelvin. pressure (float): The pressure in Pascals.

Returns:

float: The data in the output unit.

acom_music_box.utils.convert_pressure(data, key)#

Convert the pressure from the input data to Pascals.

Args:

data (dict): The input data. key (str): The key for the pressure in the input data.

Returns:

float: The pressure in Pascals.

acom_music_box.utils.convert_temperature(data, key)#

Convert the temperature from the input data to Kelvin.

Args:

data (dict): The input data. key (str): The key for the temperature in the input data.

Returns:

float: The temperature in Kelvin.

acom_music_box.utils.convert_time(data, key)#

Convert the time from the input data to seconds.

Args:

data (dict): The input data. key (str): The key for the time in the input data.

Returns:

float: The time in seconds.

acom_music_box.utils.convert_to_number_density(data, input_unit, temperature, pressure)#

Convert from some other units to mol m-3

Args:

data (float): The data to convert in the input unit. input_unit (str): The input units temperature (float): The temperature in Kelvin. pressure (float): The pressure in Pascals.

Returns:

float: The data in the output unit.

acom_music_box.utils.extract_unit(data, key)#

Extract the value and unit from the key in data.

acom_music_box.utils.get_available_units()#

Get the list of available units for conversion.

Returns:

list: The list of available units.

On this page
Show Source