FogCom

FogCom is a subsequent executable research implementation for OpenRaaS. It provides a simulation and policy-design sandbox for partially observable broker-provider resource selection. It isolates one orchestration subproblem: a broker selects a compute provider and admits a bounded set of model repositories or sources, while the selected provider chooses one source using provider-observed link information and its own preference.

FogCom is a research prototype. It does not implement or deploy the complete OpenRaaS platform, and v0.2 is not a bit-exact reproduction of the archived evaluation record.

What FogCom models

An application request needs a compute provider and a model repository that holds the required VM or container-image data. The simulated broker has incomplete link information, whereas the selected compute provider may observe more about its incident links and may optimize a different objective.

For each request, FogCom:

1. ranks idle compute providers using estimated social welfare;
2. ranks eligible model repositories using the same public estimate;
3. exposes task, provider, strategy-tag, and source features to PPO;
4. interprets two PPO logits per source position as (drop, accept);
5. sends the resulting admitted bounded set to the compute provider;
6. lets the provider choose one source using its provider-observed links;
7. simulates upload, image-block transfer, processing, and result download;
8. reports the implemented PPO reward and realized system metrics separately.

Estimated social welfare is used for pre-ranking. PPO is trained with the implemented transfer-time-shaped reward; realized social welfare is recorded as a separate evaluation metric.

The four built-in provider preferences are:

• no additional preference;
• prefer longer provider-observed image-transfer time;
• prefer shorter provider-observed image-transfer time;
• prefer repositories in the same synthetic provider domain.

The classifier under packages/alg/train_eval_net.py is a separate experiment. The main environment inserts a simulator-provided strategy tag. With the checked-in no_tag_mode: 1, the wrapper masks that tag with a constant all-ones vector instead of using classifier output.

v0.2 executable contract

The checked-in configuration has a 50-dimensional observation: six task/provider values, four strategy-tag positions, and four values for each of ten source positions. The actor and critic use hidden widths 64 and 32. The actor emits 20 values, interpreted as two logits per source position, and one PPO update follows each 1,000-sample rollout.

This executable contract differs from the archived evaluation record:

Contract	Current v0.2 executable	Archived evaluation record
Observation	50 values	51 values
Hidden widths	64 and 32	2048 and 512
Source-set action	two logits per source, decoded by argmax	ten recorded Gaussian parameter pairs, followed by sampling, sigmoid, and rounding
Interactions per update	1,000	20,000
Training signal	transfer-time-shaped reward, scaled by reward_scale	realized-welfare one-step record
Provider descriptor	scripted tag, masked in the default no-tag run	scripted four-class descriptor in the welfare record

The archive does not preserve every action-distribution transform, categorical encoding, or response-restriction mapping. Current checkpoints and tests therefore validate the v0.2 executable rather than claiming bit-exact archive reproduction.

Relationship to OpenRaaS

FogCom represents only part of the scheduling responsibility associated with an OpenRaaS MasterNode. A simulated compute provider is closest to an OpenRaaS Computor, and a model repository is closest to a Depository. OpenRaaS Filestore behavior is outside the current model.

See docs/openraas-context.md for the exact mapping and the boundaries of that relationship.

Quick start

Create the tested CPU-oriented Conda environment:

conda env create -f environment.yml
conda activate fogcom
python -m pytest -q

The environment targets Python 3.10, PyTorch 2.5.1, and Gym 0.26.2. The code continues to expose the legacy four-value step interface internally; the tests lock down the interface used by this repository.

Review config.yml, then train:

python main.py

Evaluate a saved checkpoint:

python test.py

Both commands read config.yml from the current working directory. Training and evaluation artifacts are written below results_path.

checkpoint.pth is the authoritative atomic schema-v2 actor/critic bundle. The separate act_grad.pth and cri_grad.pth files remain available as legacy compatibility fallbacks. See docs/experiments.md for the load order and weights-only warm-start boundary.

Default experiment profile

The checked-in configuration is an experimental snapshot, not a canonical benchmark:

• gamma: 0 makes the configured return one-step and myopic;
• no_tag_mode: 1 masks the simulator-provided strategy tag;
• workers: 0 performs exploration in the main process;
• gpu_id: -1 selects CPU execution;
• eval_horizon: 100 preserves the historical evaluation length while making it explicit and configurable.

Record the configuration, commit, environment, random seed, and checkpoint whenever results need to be reproduced.

Repository map

Path	Purpose
main.py	PPO training entry point.
test.py	Actor-checkpoint evaluation entry point.
config.yml	Simulation, training, evaluation, and output settings.
packages/env/fogcom/	Entities, links, timing, costs, and environment logic.
packages/alg/PPO.py	PPO actor, critic, collection, update, and checkpoint logic.
packages/alg/eval.py	Synchronous evaluation and metric logging.
packages/alg/train_eval_net.py	Separate provider-strategy classifier.
tests/	Deterministic unit and regression tests.
docs/	Model, OpenRaaS mapping, experiment, and historical notes.
experiments/legacy/	Historical scripts retained outside the supported path.
artifacts/legacy/	Historical generated figures and tables.

Documentation

• OpenRaaS context explains terminology and scope.
• Implemented model is the mathematical contract for current code.
• Conceptual model reconstructs the motivation and broader formulation from the original Chinese notes while separating unimplemented ideas.
• Experiments covers configuration, outputs, and reproducibility.
• The original Chinese notes are preserved as a raw historical archive under docs/archive/.

GitHub-compatible display equations use fenced math blocks.

Current limitations

• Compute-provider assignment is greedy; PPO admits model sources only.
• The default strategy tag is simulator knowledge, not classifier output.
• Resource contention, mobility, and runtime-file storage are simplified.
• Environment reset clears the realized pair-link cache. A distinct-node pair's base link is then sampled once and cached for the episode, while compute/repository endpoint resources, bandwidth, and latency are resampled each slot. The effective link therefore changes with current endpoint limits even though its base pair sample remains cached.
• The simulator reserves zero transfer bandwidth for an omitted or local repository leg; sampled base links between distinct nodes are strictly positive.
• The project does not ship large datasets or trained checkpoints.
• Full deterministic reproduction across operating systems is not guaranteed.

License

FogCom is licensed under the Apache License 2.0. ElegantRL-derived components retain their original Apache-2.0 attribution and modification record in THIRD_PARTY_NOTICES.md.